Webhooks

Payments do not always finish while your request is open. A customer approves on their phone, a bank settles minutes later, a refund clears overnight. Webhooks are how Orchestrate tells you the outcome.

Two delivery channels

Orchestrate can deliver an event two ways. Both carry the same events and the same payloads; what differs is scope and whether the delivery is signed.

	Project endpoint	Per-resource `webhook_url`
Configured	In your dashboard, once	On the intent, checkout session or payout, per resource
Scope	Every event you subscribe to, across the project	Only that payment or payout
Signed	Yes, HMAC with the endpoint secret	No

Pick a project endpoint when you want one handler for everything, a webhook_url when you want the notification tied to the resource you just created — or both.

Deliveries to a webhook_url are not signed. Anyone who learns the URL can post to it. Treat the payload as a notification only: re-read the resource from the API before you act on it.

For anything that moves value on your side — fulfilling an order, crediting a wallet — use a project endpoint and verify the signature, or re-fetch the resource. Never trust an unsigned body.

Events

Every event below is delivered on both channels. On a project endpoint you subscribe per event; the subscribe as column is the name you pick in your dashboard.

Event	Subscribe as	Fired when
`payment.initiated`	`payment_initiated`	A payment is created.
`payment.completed`	`payment_captured`	The payment succeeded.
`payment.failed`	`payment_failed`	The payment failed for good.
`payment.expired`	`payment_expired`	The payment expired before it completed.
`payment.refunded`	`payment_refunded`	A refund brought the payment to fully refunded.
`payment.partially_refunded`	`payment_refunded`	A refund cleared, part of the payment remains.
`payment.attempt.completed`	`payment_attempt_completed`	One attempt on a payment succeeded.
`payment.attempt.failed`	`payment_attempt_failed`	One attempt on a payment failed.
`payout.initiated`	`payout_initiated`	A payout is created.
`payout.completed`	`payout_completed`	The payout was delivered.
`payout.failed`	`payout_failed`	The payout failed.

Subscribing to all on a project endpoint gives you every event above, including future ones. Key your handler on the event field rather than on a fixed list.

A failed attempt does not mean a failed payment. payment.attempt.failed can be followed by a successful attempt on the same payment. Act on payment.* for the final outcome and treat payment.attempt.* as detail.Both refund events share the payment_refunded subscription; read the event field to tell a full refund from a partial one.

Delivery guarantees

Deliveries are retried up to five times on failure. Delivery is at-least-once and order is not guaranteed: you can receive the same event twice, or a later event before an earlier one. Build your handler accordingly:

Be idempotent. Key on the payment id plus the event name and ignore repeats.
Do not rely on order. Read the current status from the payload or the API rather than inferring it from the sequence of events.
Respond quickly. Return 2xx as soon as you have stored the event; do the work afterwards.

Headers

Project endpoint deliveries:

X-Pulse-Id: <endpoint id>
User-Agent: Pulse | Orqex +https://orqex.com

Payment webhook_url deliveries:

X-Payment-Event: payment.completed
X-Payment-Id: pi_...
X-Attempt-Id: att_...      # attempt events only
User-Agent: Orqex +https://orqex.com

Payout webhook_url deliveries:

X-Payout-Event: payout.completed
X-Payout-Id: po_...
User-Agent: Orqex +https://orqex.com

Verifying a project endpoint

Each project endpoint has its own secret, shown when you create it in the dashboard. Deliveries carry an HMAC signature computed over the raw request body with that secret. Compare it in constant time, against the raw body — not a re-encoded version of the parsed JSON.

$payload   = file_get_contents('php://input');
$expected  = hash_hmac('sha256', $payload, $secret);

if (! hash_equals($expected, $signatureHeader)) {
    http_response_code(400);
    exit;
}

$event = json_decode($payload, true);

Payloads

Payment events

{
  "event": "payment.completed",
  "payment": {
    "id": "pi_...",
    "amount": { "value": 50, "formatted": "$50.00", "short": "$50", "currency": "USD" },
    "status": "completed",
    "description": "Order #1042",
    "return_url": "https://example.com/orders/1042/return",
    "statement_descriptor": null,
    "receipt_email": null,
    "metadata": {},
    "completed_at": "...",
    "failed_at": null,
    "refunded_at": null,
    "partially_refunded_at": null,
    "expires_at": "...",
    "created_at": "..."
  },
  "attempt": {
    "id": "att_...",
    "status": "completed",
    "method_code": "test",
    "failure_code": null,
    "is_failover": false,
    "failover_decision": null
  },
  "customer": { "id": "cus_...", "first_name": "Ada", "last_name": "Lovelace", "email": "[email protected]" },
  "project": { "id": "prj_...", "name": "Acme" },
  "timestamp": "..."
}

Attempt events

Same shape, with more detail on attempt — it adds amount, country, next_action, completed_at, failed_at and created_at — and a shorter payment block that carries only created_at among the timestamps.

Refund events

{
  "event": "payment.refunded",
  "refund": {
    "id": "ref_...",
    "amount": { "value": 50, "formatted": "$50.00", "short": "$50", "currency": "USD" },
    "status": "completed",
    "reason": "requested_by_customer",
    "created_at": "..."
  },
  "payment": {
    "id": "pi_...",
    "amount": { "value": 50, "formatted": "$50.00", "short": "$50", "currency": "USD" },
    "status": "refunded"
  },
  "customer": { "id": "cus_...", "first_name": "Ada", "last_name": "Lovelace", "email": "[email protected]" },
  "timestamp": "..."
}

Payout events

{
  "event": "payout.completed",
  "payout": {
    "id": "po_...",
    "amount": { "value": 50, "formatted": "$50.00", "short": "$50", "currency": "USD" },
    "method": "...",
    "status": "completed",
    "reference": "batch-42-line-7",
    "description": "Supplier settlement",
    "customer": { "id": "cus_...", "first_name": "Ada", "last_name": "Lovelace", "email": "[email protected]" },
    "instrument": { "id": "pin_...", "type": "bank_account", "...": "..." },
    "gateway": { "transaction": { "id": "...", "reference": "...", "external_id": "..." } },
    "fee_amount": 0,
    "failure": { "code": null, "message": null }
  }
}

When a webhook never arrives

If your endpoint was down or a payment looks stuck, do not poll in a loop. Ask Orchestrate to re-check the payment with the provider: see Requery. For payouts, use GET /payouts/{id}/sync — see Payouts.

Get started

Payments

Payouts

Events

Utilities

MCP

Two delivery channels

Events

Delivery guarantees

Headers

Verifying a project endpoint

Payloads

Payment events

Attempt events

Refund events

Payout events

When a webhook never arrives

​Two delivery channels

​Events

​Delivery guarantees

​Headers

​Verifying a project endpoint

​Payloads

​Payment events

​Attempt events

​Refund events

​Payout events

​When a webhook never arrives

Two delivery channels

Events

Delivery guarantees

Headers

Verifying a project endpoint

Payloads

Payment events

Attempt events

Refund events

Payout events

When a webhook never arrives