API Reference
Webhook deliveries
Handle deliveries, deduplication, and manual resend.
Delivery behavior
Zippy delivers webhooks on a best-effort basis. Each live event is POSTed to every active endpoint registered for your business. There is no guaranteed delivery ordering — handlers must tolerate events arriving out of sequence.
Response requirements
- Respond with HTTP 2xx within a few seconds.
- Content-Type of the Zippy request is
application/json; charset=utf-8. - Request headers include
X-Zippy-Signature,X-Zippy-Webhook-Id, andX-Zippy-Delivery-Id.
Deduplication
| Name | Type | Description |
|---|---|---|
X-Zippy-Webhook-Id | uuid | Stable event identifier. The same logical event always uses the same ID. |
X-Zippy-Delivery-Id | uuid | Unique per delivery attempt. Changes on manual resend. |
envelope id | uuid | JSON body field matching X-Zippy-Webhook-Id. Safe primary dedupe key. |
Deduplicate on envelope id and/or X-Zippy-Webhook-Id. Use X-Zippy-Delivery-Id to distinguish separate delivery attempts for the same event when debugging resends.
Manual resend
When a delivery fails (timeout, connection error, or non-2xx response), inspect the attempt in Developer → Webhooks → Deliveries at zippypay.io. Manual resend creates a new delivery attempt and re-POSTs the event with a new X-Zippy-Delivery-Id.
Operational checklist
- Monitor failed deliveries in Developer → Webhooks → Deliveries.
- Alert on sustained non-2xx or timeout spikes.
- Verify signatures before enqueueing work — reject forgeries early.
- Process events asynchronously if fulfillment takes longer than a few seconds.