Webhooks

Webhooks are the platform's only push notification channel. When an invoice changes state, the platform POSTs a signed JSON body to the merchant's configured webhook URL.

What they are#

• HTTP POST with Content-Type: application/json.
• Signed with HMAC-SHA256 using the merchant's webhook_secret.
• At-least-once — one dispatch per transition, retried automatically with exponential backoff until delivered or exhausted.
• Retry-on-demand — operators retry failed deliveries from the dashboard.
• Idempotent-friendly — X-Webhook-ID is stable across retries of the same event.

What they guarantee#

• At-most-once delivery per transition for the automatic path. Manual retries cause at-least-once behaviour on the events you choose to retry.
• Order in dispatch — events are emitted in the order transitions happen. Arrival order may differ after manual retries.
• Integrity — the signature cryptographically binds the body to the merchant's secret.

What they do not guarantee#

• Delivery. If your endpoint is down, you see a failed delivery in the dashboard.
• Order of arrival. Trust status in the payload, not the order events come in.
• Freshness. Receive X-Webhook-Timestamp and optionally reject stale events on your side.

Reference pages#

• Event types — the full list.
• Payload schema — the JSON contract.
• Signature scheme — how to verify.
• Delivery semantics — automatic retries, backoff schedule, URL requirements.