Skip to main content

Webhooks

There are two places to tell us where your events go, and you can use both.

  • Webhook endpoints in the dashboard. Under Settings, Webhook Endpoints, save a URL once with the events it should receive. It then receives those events for every payment intent, refund, dispute, subscription and payout of its tenant, including the ones created before you saved it. When your URL changes, you edit it in one place.
  • webhooks on a resource. Pass a list of endpoints when you create a payment intent, refund, payout, plan or subscription. These receive the events of that one resource. This is the easiest way to route a single payment somewhere specific, or to keep everything in code.

An event is delivered to both kinds of endpoint. If the same URL is saved in the dashboard and passed on the resource, it receives the event once, with the secret you passed on the resource.

A dashboard endpoint belongs to one tenant, so your sandbox and production tenants each have their own. Disable an endpoint to pause it without losing its settings.

By default each endpoint receives every event. To receive only a subset, set the events array on that webhook endpoint (for example ["payment.success"]). The type and status fields are always present (and sub_status on payment, refund, and payout events), so you can also filter in your own code.

When a customer disputes a payment with their bank or wallet, the payment intent's webhook endpoints also receive dispute.created, dispute.updated, and dispute.closed. See Dispute Webhook.

Authentication​

On each webhook endpoint you can provide an optional secret, which is sent in a header named Orchestrapay-Webhook-Secret so you can authenticate the request. A dashboard endpoint always has one: set your own, or leave it empty and we generate it. You can read it back on the endpoint's page.

Delivery and retries​

We POST each event to your endpoints in real time. A delivery is successful only when your endpoint returns a 2xx status code within 3 seconds. Return the status code before running any heavy processing: if your endpoint takes longer than 3 seconds we abort the connection and count the delivery as failed, as we do for any non-2xx response, redirect, or connection error.

When a delivery fails we retry it with exponential backoff for up to 3 days, after which we stop. In a sandbox we retry a few times over a few hours. Each endpoint you configured is delivered to, and retried, independently.

Blocked URLs​

When every delivery to a URL has failed for 5 days in a row, we block that URL for its tenant and stop sending to it. This covers a URL saved in the dashboard and a URL passed in webhooks alike, so an endpoint you retired years ago and that old subscriptions still name does not keep being retried.

We email your organisation's owners, and anyone who can manage webhooks in that tenant, twice: once when a URL has been failing for a day, with the date it will be blocked, and again when it is blocked.

While a URL is blocked, its events are still recorded, with the status skipped, and nothing is sent. Under Settings, Webhook Endpoints, the URL is listed as Blocked. Unblock it there once your endpoint is back: events skipped in the last 3 days are sent right away, and older ones can be resent one by one from the Webhooks page. You can also block a URL yourself from the same page, without waiting for it to fail.

Deliveries are at-least-once: the same event may arrive more than once, and events are not guaranteed to arrive in the order they occurred. Use the envelope id (evt_...) to deduplicate, and rely on each object's status rather than delivery order to determine the current state.

Payload​

The core of the webhook payload has the same properties, albeit each status or sub-statuses may have additional properties.

You can find the exhaustive list of payloads in the Webhook Payloads page.