POST to each URL you subscribe with Create a Webhook. Payout events cover payouts your backend sends and cash outs from the widget, in both products. Transaction events cover value moving inside ZBD, for programs where ZBD holds balances.
Payout events
Transaction events
The payload carries
transaction_id, type, reference_id, project_id, and the transaction’s movements, in the same shape as Get a Transaction. It’s signed the same way as payout events.
Payout payload
Your own ID for the payout, if you sent one. Use it to match the event to your records.
Verifying a webhook
Every webhook is signed. TheX-ZBD-Signature header carries the signature, and X-ZBD-Signature-Key-Id names the key that signed it.
- Fetch ZBD’s public keys from
GET /api/v1/webhooks/jwks.jsonand cache them. - Pick the key that matches
X-ZBD-Signature-Key-Id. - Check the signature over the raw request body before you act on the event.
Handling deliveries
- Respond quickly with a
2xx. Do the work after you respond. ZBD retries deliveries that fail or time out. - Deduplicate on
event_id. A retry can deliver the same event more than once. - Don’t rely on order. Use
occurred_at, and the payout’s current status from Get a Payout if you need to be sure.