Overview
ZBD sends webhook events to your configured HTTPS endpoint when a widget cashout or reversal changes status. Your endpoint validates the signature, acknowledges receipt, and processes the event asynchronously.
Webhook configuration is completed with ZBD during publisher onboarding. ZBD provides the shared signing secret used to sign each webhook request.
The MVP does not support subscribing to individual event types. ZBD sends all widget webhook event types to the configured endpoint, and your system should filter by the event_type field.
Webhook Delivery Request
ZBD sends each event as an HTTP POST request:
Your endpoint should return HTTP 200 within 10 seconds to acknowledge receipt. Any non-200 response, timeout, 5xx response, or connection failure triggers retry.
Validate the webhook signature against the raw request body before processing the event.
Webhook Event Types
Cashout Webhook Events
Cashout lifecycle webhooks identify the event, reference the publisher’s user identifier, include the current status, include the amount, and include the time the event occurred at the bank or inside ZBD.
Cashout Initiated
Cashout Completed
Cashout Failed
Cashout Returned
Cashout Payload Fields
Reversal Webhook Events
Reversal status webhooks identify the reversal action, the new status, the reversal method, the amount, and the timestamp.
Reversal Completed
Reversal Failed
Reversal Payload Fields
Webhook Event Sources
cashout.initiated events are generated when the user submits a cashout through the ZBD Widget and ZBD submits the ACH to the partner bank.
cashout.completed, cashout.failed, and cashout.returned events are generated from partner bank webhook callbacks. ZBD translates the bank-level status update into the publisher-facing event.
reversal.status_changed events are generated when a reversal transitions between states. Instant reversals emit on completion. Queued bank-level reversals emit when ZBD records the final outcome from the partner bank.
Retries
ZBD attempts initial delivery within seconds of event generation. If your endpoint does not return HTTP 200, ZBD retries with exponential backoff: roughly 1 minute, 5 minutes, 30 minutes, 2 hours, then 12 hours between attempts.
After approximately five failed delivery attempts over roughly 15 hours, the event moves to a dead-letter queue and ZBD operations is alerted to investigate.
Idempotency
Webhook delivery is at least once. The same event may be delivered more than once if a retry happens. Store and deduplicate by event_id.
Auditability
ZBD logs each webhook delivery attempt, including the attempt timestamp, response or timeout reason, and final outcome.
