Skip to main content
Webhooks push event payloads to your HTTPS endpoint when objects change in your organisation: for example when a customer completes a payment or a subscription becomes active. They are the primary way to keep your system in sync without polling.

​
Why verify every request

Payloads include payment amounts and status fields. Anyone who can discover your URL could otherwise POST forged “Succeeded” events. ZBX signs each delivery with your organisation’s webhook private key. You verify with the public key from the dashboard. See Verify Webhook Signatures.

​
Delivery model

  1. An internal event is processed (Type + Action, for example Payment + Updated)
  2. The payload’s event field is set to Type.Action (for example Payment.Updated)
  3. Platform POSTs JSON to your org webhook_url with signature headers
  4. Delivery status is stored (and listed under API & Webhook → Webhooks)
If your endpoint does not return a 2xx status, the delivery is marked failed. Use the dashboard (or events API) to retry or replay. Manual retries enforce a 60 second cooldown per event.

​
Handler checklist

  1. Accept POST with JSON body
  2. Verify signature + timestamp freshness
  3. Confirm org_id
  4. Branch on event
  5. Apply business logic idempotently
  6. Return 2xx after durable persistence