diff --git a/api-reference/preview/paxos-v2-preview-orchestration.openapi.json b/api-reference/preview/paxos-v2-preview-orchestration.openapi.json
index b6a49b64..18c7f23e 100644
--- a/api-reference/preview/paxos-v2-preview-orchestration.openapi.json
+++ b/api-reference/preview/paxos-v2-preview-orchestration.openapi.json
@@ -612,6 +612,7 @@
"OrchestrationStatus": {
"type": "string",
"enum": [
+ "PENDING_APPROVAL",
"PROCESSING",
"COMPLETED",
"FAILED"
diff --git a/api-reference/webhooks/orchestration-pending-approval.mdx b/api-reference/webhooks/orchestration-pending-approval.mdx
new file mode 100644
index 00000000..7037837a
--- /dev/null
+++ b/api-reference/webhooks/orchestration-pending-approval.mdx
@@ -0,0 +1,15 @@
+---
+title: "orchestration.pending_approval"
+description: "Webhook triggered when an orchestration requires maker-checker approval"
+openapi: "webhooks-openapi.json webhook orchestration.pending_approval"
+---
+
+Triggered when an ad-hoc orchestration requires maker-checker approval before processing can begin.
+
+
+Webhook payloads contain only event metadata. Use the [Get Event API](/api-reference/endpoints/events/get-event) with the event ID to retrieve full details.
+
+
+## Event Object Structure
+
+The Get Event API returns an [`orchestration_status_change`](/api-reference/events/orchestration-status-change-object) object with orchestration status details.
diff --git a/api-reference/webhooks/webhooks-openapi.json b/api-reference/webhooks/webhooks-openapi.json
index c9585f59..b57042e4 100644
--- a/api-reference/webhooks/webhooks-openapi.json
+++ b/api-reference/webhooks/webhooks-openapi.json
@@ -207,6 +207,34 @@
"description": "Triggered when a KYC refresh process expires without completion. Your endpoint should respond with a 2xx status code to acknowledge receipt. Use the event ID to call the Get Event API for full details."
}
},
+ "orchestration.pending_approval": {
+ "post": {
+ "requestBody": {
+ "description": "Webhook payload containing event metadata. Use the event ID with the Get Event API to retrieve full details.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookEvent"
+ },
+ "example": {
+ "id": "bd019f1c-89a7-4372-9d21-eaad9280dc41",
+ "type": "orchestration.pending_approval",
+ "source": "com.paxos",
+ "time": "2025-01-07T14:30:02Z",
+ "object": "event"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Webhook successfully received"
+ }
+ },
+ "summary": "Orchestration Pending Approval",
+ "description": "Triggered when an ad-hoc orchestration requires maker-checker approval before processing can begin. Your endpoint should respond with a 2xx status code to acknowledge receipt. Use the event ID to call the Get Event API for full details."
+ }
+ },
"orchestration.processing": {
"post": {
"requestBody": {
@@ -1577,6 +1605,7 @@
"identity.kyc_refresh.started",
"identity.kyc_refresh.completed",
"identity.kyc_refresh.expired",
+ "orchestration.pending_approval",
"orchestration.processing",
"orchestration.completed",
"orchestration.failed",
@@ -1764,7 +1793,7 @@
},
"status": {
"type": "string",
- "enum": ["PROCESSING", "COMPLETED", "FAILED"],
+ "enum": ["PENDING_APPROVAL", "PROCESSING", "COMPLETED", "FAILED"],
"title": "Orchestration Status",
"description": "Status of the orchestration"
}
diff --git a/docs.json b/docs.json
index e84d0dcc..2f5e0851 100644
--- a/docs.json
+++ b/docs.json
@@ -938,6 +938,7 @@
{
"group": "Hooks",
"pages": [
+ "api-reference/webhooks/orchestration-pending-approval",
"api-reference/webhooks/orchestration-processing",
"api-reference/webhooks/orchestration-completed",
"api-reference/webhooks/orchestration-failed"
diff --git a/guides/developer/orchestrations/orchestrations.mdx b/guides/developer/orchestrations/orchestrations.mdx
index a00b367c..4d3fc9bb 100644
--- a/guides/developer/orchestrations/orchestrations.mdx
+++ b/guides/developer/orchestrations/orchestrations.mdx
@@ -120,19 +120,24 @@ To use orchestrations, you'll need the following OAuth scopes when [authenticati
## Monitoring Orchestration Status
-Orchestrations can exist in three states. To monitor them there's a few options.
+Orchestrations can exist in four states. To monitor them there's a few options.
```mermaid
stateDiagram-v2
+ [*] --> PENDING_APPROVAL: Approval Required
[*] --> PROCESSING: Orchestration Created
+ PENDING_APPROVAL --> PROCESSING: Approved
+ PENDING_APPROVAL --> FAILED: Rejected
PROCESSING --> COMPLETED: Success
PROCESSING --> FAILED: Error
```
+Ad-hoc orchestrations that require maker-checker approval enter the `PENDING_APPROVAL` state before processing begins. Once approved, they transition to `PROCESSING`. If rejected, they transition directly to `FAILED`.
+
### Recommended: Using Webhooks
> Subscribe to orchestration webhooks for real-time status monitoring. This is the recommended approach as it provides immediate notifications without polling.