Webhooks

Webhooks let Orchestr notify your server about events as they happen — a payment succeeding, a checkout session completing, and so on — instead of you polling the API. Orchestr delivers each event as an HTTPS POST to an endpoint you register.

The event envelope

Every webhook body is a JSON envelope with a stable shape. The event-specific data lives under data; its fields depend on the event type.

{
  "id": "evt_1a2b3c4d5e6f7081",
  "type": "payment.succeeded",
  "created": 1719056400,
  "data": {
    "transaction_id": "txn_9f8e7d6c",
    "status": "completed",
    "amount": 42.00,
    "currency": "GBP"
  }
}

Field	Type	Description
id	string	Unique event ID. Use it for idempotency.
type	string	The event type, e.g. payment.succeeded (see Event types).
created	integer	When the event was created, as a Unix timestamp (seconds).
data	object	The event payload. Shape varies by type. Fields are snake_case.

Delivery headers

Header	Value
Content-Type	application/json
X-Signature	t=<unixSeconds>, v1=<hex>[, v1=<hex>...] — the signature over the webhook body.

Verifying webhooks

Webhooks are signed exactly like API responses: the HMAC-SHA256 is computed over timestamp + body (no path). Verify the signature on the raw request body before parsing it, and reject anything that does not verify.

See Signing → Verifying a response or webhook for ready-to-use verification snippets in every supported language. Because a webhook may carry multiple v1 values during a secret rotation, accept the event if any v1 matches.

Verify before you trust

Anyone can POST to your webhook URL. Treat an event as genuine only after its X-Signature verifies against one of your active signing secrets.

Responding to webhooks

• Return a 2xx status code as soon as you have safely received the event. Any other outcome is treated as a failure and the delivery is retried.
• Acknowledge fast, process asynchronously. Orchestr's read timeout is 30 seconds; do slow work (database writes, downstream calls) after responding, ideally off a queue.
• Make your handler idempotent — the same event may arrive more than once. See Retries → Idempotency.

Registering endpoints

Webhook endpoints are created and managed from the Orchestr Dashboard. For each endpoint you configure:

• URL — must be HTTPS and publicly reachable. Private, internal, and cloud-metadata addresses are rejected (this is re-checked at delivery time, not only at registration).
• Subscribed events — choose specific event types, or subscribe to all of them by leaving the selection empty.
• Name / description — optional, for your own reference.

You can register up to 10 endpoints per account. Endpoints can be paused or deleted from the Dashboard at any time.

Next

• Event types — the catalogue of events and their payloads.
• Retries — delivery attempts, backoff, and idempotency.