From 212bb21739c9ac47f7c5232f639b1957802a70e2 Mon Sep 17 00:00:00 2001 From: pablofelitti-paxos Date: Tue, 17 Feb 2026 13:12:37 -0300 Subject: [PATCH] AO-1017: Add PENDING_APPROVAL orchestration status to public documentation Add PENDING_APPROVAL to the orchestration status enum across all docs: OpenAPI specs, webhook definitions, state diagram, and event object docs. Also add the new orchestration.pending_approval webhook event for maker-checker approvals. Co-Authored-By: Claude Opus 4.6 --- .../orchestration-status-change-object.mdx | 4 +-- ...axos-v2-preview-orchestration.openapi.json | 1 + .../orchestration-pending-approval.mdx | 15 +++++++++ api-reference/webhooks/webhooks-openapi.json | 31 ++++++++++++++++++- docs.json | 1 + .../orchestrations/orchestrations.mdx | 7 ++++- 6 files changed, 55 insertions(+), 4 deletions(-) create mode 100644 api-reference/webhooks/orchestration-pending-approval.mdx diff --git a/api-reference/events/orchestration-status-change-object.mdx b/api-reference/events/orchestration-status-change-object.mdx index 6a7576f1..5c29ebcc 100644 --- a/api-reference/events/orchestration-status-change-object.mdx +++ b/api-reference/events/orchestration-status-change-object.mdx @@ -3,7 +3,7 @@ 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,7 +18,7 @@ The client-specified ID of the orchestration for replay protection and lookup. Status of the orchestration: -**Available options:** `PROCESSING`, `COMPLETED`, `FAILED` +**Available options:** `PENDING_APPROVAL`, `PROCESSING`, `COMPLETED`, `FAILED` 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.