Skip to main content
There are two families of orchestration webhook events: a high-level family that fires once per top-level status transition, and a granular family that fires at each sub-state change. You do not need to implement both. Pick the one that fits your integration, or combine them only where the specific cases below apply.

​
High-Level Status Events

These events fire once per top-level status transition: Each event fires exactly once per transition. Retrieve full details using the Get Event API; the object type is orchestration_status_change. Use these when:
  • You only need to know the final outcome (completed or failed) to trigger a downstream action.
  • Your retry logic fires on any failure regardless of the failure reason.
  • You want the simplest integration with the fewest subscriptions.

​
Granular status_details Events

These events fire at sub-state transitions within PENDING, PROCESSING, FAILED, and REJECTED. They give you more detail than the high-level events. Each maps to a specific status_details slug: Retrieve full details using the Get Event API; the object type is orchestration_status_details_change. Use these when:
  • You display orchestration sub-state to end users (for example, “Conversion in progress” or “Awaiting approval”).
  • You handle different failure reasons differently, such as routing conversion_failed to a retry queue but policy_rejected to a support escalation.
  • You want to prompt customer action when awaiting_action_from is AWAITING_ACTION_FROM_CLIENT.

​
Using Both Families Together

Implement both when you want simple failure handling and detailed sub-state tracking at the same time. High-level events keep your core logic simple. Granular events add specificity where you need it. A common pattern:
  • Subscribe to orchestration.failed for retry logic. It fires immediately on failure regardless of the specific reason.
  • Subscribe to orchestration.status_details.conversion_failed and orchestration.status_details.destination_transfer_failed separately to route each failure type to different handlers.
  • Subscribe to orchestration.status_details.pending_customer_approval to prompt the user to approve without polling.
Each webhook fires independently. Make handlers idempotent and deduplicate on event ID. The same event can be delivered more than once if your endpoint does not respond with 2xx. Use event type only for routing to the correct handler.

​
Polling as a Fallback

If you cannot subscribe to webhooks, poll Get Orchestration and inspect status and status_details directly. The field shapes are identical to what the orchestration_status_details_change event object returns.
Questions? Contact Support.