AO-1017: Add PENDING_APPROVAL orchestration status to documentation

api-reference/events/orchestration-status-change-object.mdx

@@ -1,9 +1,9 @@
 ---
 title: "orchestration_status_change"
 description: "Event object returned for orchestration status change events"
 ---
 
-This object is returned by the [Get Event API](/api-reference/endpoints/events/get-event) when the event type is `orchestration.processing`, `orchestration.completed`, or `orchestration.failed`.
+This object is returned by the [Get Event API](/api-reference/endpoints/events/get-event) when the event type is `orchestration.pending_approval`, `orchestration.processing`, `orchestration.completed`, or `orchestration.failed`.
 
 ## Object Fields
 
@@ -18,10 +18,10 @@
 <ResponseField name="status" type="string" required>
 Status of the orchestration:
 
-**Available options:** `PROCESSING`, `COMPLETED`, `FAILED`
+**Available options:** `PENDING_APPROVAL`, `PROCESSING`, `COMPLETED`, `FAILED`
 </ResponseField>
 
 <ResponseField name="orchestration_rule_id" type="string">
 The ID of the orchestration rule that triggered this orchestration. This field will not be present for ad-hoc orchestrations. (optional)
 </ResponseField>
 

api-reference/preview/paxos-v2-preview-orchestration.openapi.json

@@ -612,6 +612,7 @@
       "OrchestrationStatus": {
         "type": "string",
         "enum": [
+          "PENDING_APPROVAL",
           "PROCESSING",
           "COMPLETED",
           "FAILED"

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.
+
+<Note>
+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.
+</Note>
+
+## Event Object Structure
+
+The Get Event API returns an [`orchestration_status_change`](/api-reference/events/orchestration-status-change-object) object with orchestration status details.

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"
           }

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"

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.
 
 <div style={{ display: 'flex', justifyContent: 'center' }}>
 
 ```mermaid
 stateDiagram-v2
+    [*] --> PENDING_APPROVAL: Approval Required
     [*] --> PROCESSING: Orchestration Created
+    PENDING_APPROVAL --> PROCESSING: Approved
+    PENDING_APPROVAL --> FAILED: Rejected
     PROCESSING --> COMPLETED: Success
     PROCESSING --> FAILED: Error
 ```
 
 </div>
 
+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.