> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paxos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Integration Guide

> When to use high-level orchestration status webhooks versus granular status_details events.

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:

| Event                                                                          | Fires when                                                          |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| [`orchestration.pending`](/api-reference/webhooks/orchestration-pending)       | Orchestration enters `PENDING`, awaiting customer or admin approval |
| [`orchestration.processing`](/api-reference/webhooks/orchestration-processing) | Orchestration enters `PROCESSING` and execution has started         |
| [`orchestration.completed`](/api-reference/webhooks/orchestration-completed)   | Orchestration completes successfully                                |
| [`orchestration.failed`](/api-reference/webhooks/orchestration-failed)         | Orchestration fails                                                 |
| [`orchestration.rejected`](/api-reference/webhooks/orchestration-rejected)     | Orchestration is rejected by a policy rule                          |

Each event fires exactly once per transition. Retrieve full details using the [Get Event API](/api-reference/endpoints/events/get-event); the object type is [`orchestration_status_change`](/api-reference/events/orchestration-status-change-object).

**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:

| Event                                                                                                                                                    | Slug                               | Fires when                                                |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | --------------------------------------------------------- |
| [`orchestration.status_details.pending_customer_approval`](/api-reference/webhooks/orchestration-status-details-pending-customer-approval)               | `pending_customer_approval`        | Orchestration is waiting for customer or admin approval   |
| [`orchestration.status_details.conversion_in_progress`](/api-reference/webhooks/orchestration-status-details-conversion-in-progress)                     | `conversion_in_progress`           | Source asset conversion is in progress                    |
| [`orchestration.status_details.destination_transfer_in_progress`](/api-reference/webhooks/orchestration-status-details-destination-transfer-in-progress) | `destination_transfer_in_progress` | Conversion complete; destination transfer is settling     |
| [`orchestration.status_details.conversion_failed`](/api-reference/webhooks/orchestration-status-details-conversion-failed)                               | `conversion_failed`                | Source asset conversion could not be completed (terminal) |
| [`orchestration.status_details.destination_transfer_failed`](/api-reference/webhooks/orchestration-status-details-destination-transfer-failed)           | `destination_transfer_failed`      | Destination transfer could not be completed (terminal)    |
| [`orchestration.status_details.policy_rejected`](/api-reference/webhooks/orchestration-status-details-policy-rejected)                                   | `policy_rejected`                  | Orchestration rejected by a policy rule (terminal)        |

Retrieve full details using the [Get Event API](/api-reference/endpoints/events/get-event); the object type is [`orchestration_status_details_change`](/api-reference/events/orchestration-status-details-object).

**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](/api-reference/endpoints/orchestration/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](https://support.paxos.com).