# Webhooks

Part of the Orboni API reference: https://orboni.com/docs. This page: https://orboni.com/docs/webhooks.

Add an endpoint under **Developers → Webhooks**, one set per mode. We `POST` each event to it as JSON. Answer any 2xx within 5 seconds, connected within 3, your host’s name answering within 2; anything else is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 1 day, 1 day — about 3 days in all — and then marked failed. Failed deliveries can be sent again from the dashboard or the API.

An endpoint that does not answer — nothing in time, or a failure that took more than half of it — 3 times in a row is paused for 5 min, twice as long after each such failure since, up to 1 h. A try that falls in the pause is not sent: it fails — the dashboard says why — and counts as one of the event’s tries, and the next comes after the pause. A 2xx ends it — a delivery’s, or a test event’s sent from the dashboard. A quick 4xx or 5xx never pauses an endpoint.

An account’s endpoints, all its projects together, get about 20 seconds of sending a minute in each mode; past that its deliveries wait their turn, using no try, so a slow server delays its own account’s webhooks and nobody else’s. Past 600 events a minute in a mode, the rest go out with the retries, 100 of an account’s a minute. A suspended project’s webhooks wait until it is active again.

An endpoint is a public address of your server: a live one starts with `https://`, and addresses on a private network, localhost or ours are refused; the address is checked again before every send. Write the name in Latin letters with no dot at the end (a name in another script in its `xn--` form). A redirect is not followed — it fails the delivery, so give the final address. We keep the first kilobyte of your answer for the dashboard. Up to 16 endpoints in each mode.

To try an endpoint before a payment depends on it, press **Send test event** on it and pick a type: a sample of that event, signed with the endpoint’s secret, goes once and at once, and the dashboard shows what your server answered and what was sent. Its ids are all zeros (`evt_000…`, `cs_live_000…`), it is in no list of events and it is never retried — look such an id up and nothing is found, so fulfil nothing for it. Each person may send 10 a minute; when many are being sent at once it asks you to try again in a few seconds.

| Event | Sent when |
| --- | --- |
| `checkout.session.payment_detected` | A transfer is seen on the chain, not final yet. Tell the buyer to wait; do not fulfil. |
| `checkout.session.partially_paid` | Final transfers came, short of the amount. The link stays open for the rest. |
| `checkout.session.completed` | Paid. Fulfil the order on this one. |
| `checkout.session.expired` | The link’s time ran out unpaid. Not sent for a payment link’s payment in which nobody picked a coin. |
| `checkout.session.needs_review` | Money is held for your review (review_reason; payment_status held): it came after expiry and your project holds late payments for review, far more than asked reached a Bitcoin-style address, it came after a refund or after you closed the link, or in a stablecoin off its dollar. Do not fulfil yet; accept it in the dashboard, and checkout.session.completed follows. |
| `checkout.session.extra_received` | More money reached a completed session (a second payment, say): amount_received says how much in all. It is not a second order — send back what is not owed, then record the refund. Ask the buyer for a refund address on the same network; never send to the address the payment came from (transactions[].from): an exchange’s or a contract’s address does not credit the buyer. |
| `checkout.session.payment_reversed` | A transfer that had counted as final left the chain (a reorg, or a double-spend on a Bitcoin-style network): its status is reversed and amount_received no longer counts it. If what is left no longer pays the session, it is held for your review (review_reason reversed) and no longer complete: do not fulfil on it, and check an order you already did. It counts again if it is mined again. |
| `refund.created` | You recorded a refund. data.object is the refund, not the session. |
| `refund.voided` | A refund recorded by mistake was voided: it no longer counts in amount_refunded. data.object is the refund, with status voided. |

## Check the signature

Every request carries `Webhook-Signature: t=…,v1=…`: `v1` is the hex HMAC-SHA256 of `{t}.{raw body}` with the endpoint’s signing secret (`whsec_…`, under the endpoint in the dashboard) — Stripe’s scheme. Compare in constant time, use the raw body as received (not re-encoded JSON), and refuse a `t` more than 5 min old.

**Roll secret** under the endpoint makes a new one. For 24 hours the old secret signs too, so each request carries one `v1` per secret (`t=…,v1=…,v1=…`): accept it when any of them matches, as the sample below does, and move your server to the new secret within that time. When the account changes hands its secrets are changed at once, with no such overlap.

```php
$body = $request->getContent();
$t = '';
$signatures = [];
foreach (explode(',', (string) $request->header('Webhook-Signature')) as $part) {
    [$k, $v] = array_pad(explode('=', $part, 2), 2, '');
    if ($k === 't') {
        $t = $v;
    } elseif ($k === 'v1') {
        $signatures[] = $v;
    }
}
$expected = hash_hmac('sha256', $t.'.'.$body, config('services.orboni.webhook_secret'));
// While a secret is rolled there is one v1 per secret: any may match.
$valid = array_filter($signatures, fn ($v1) => hash_equals($expected, $v1)) !== [];

abort_unless(ctype_digit($t) && abs(time() - (int) $t) <= 300 && $valid, 400);
```

Samples in Node, Python, Ruby, Go, Java and C# are on the page, with a check of a signature that runs in your browser: https://orboni.com/docs/webhooks#try.

## Good to know

- Fulfil on checkout.session.completed, not on the buyer coming back to success_url: the buyer may close the tab, and a URL proves nothing.
- The same event can arrive more than once. Its id (evt_…) is unique: keep the ones you have handled.
- Events can arrive out of order. Read status and payment_status from the object, or retrieve the session.
- Answer first, work after: a slow endpoint times out, is retried, and is paused if it keeps timing out.
- In production, ignore events with livemode false and sessions whose id starts with cs_test_: a test key must never fulfil a real order.
