Webhooks

Lifecycle

1. You register an HTTPS URL + which events you care about (or *).
2. An event happens (order paid, gift card redeemed, etc.).
3. We enqueue one delivery per matching endpoint.
4. Our worker POSTs the payload with a Zillo-Signature header.
5. Your endpoint returns 2xx within 10 seconds to confirm receipt.
6. Non-2xx / timeout → retry at 30s, 5m, 30m, 2h, 12h, 24h (7 total attempts).
7. 5 consecutive failures → endpoint auto-disabled + email to merchant.

Headers

POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Zillo-Webhooks/1.0
Zillo-Signature: t=1717592400,v1=3a1b...c9f
Zillo-Event-Id: 8f9d...
Zillo-Event-Type: order.completed

Payload shape

{
  "id": "evt_8f9d...",          // unique event id
  "type": "order.completed",     // event type
  "created": 1717592400,         // unix seconds
  "data": { ... }                // the serialized resource
}

datamatches the resource's shape from the REST API — for order.completed, it's the same payload you'd get from GET /v1/orders/{id}.

Idempotency

Each event has a stable id. We may retry deliveries (Stripe re-delivery, your endpoint returned 5xx). Track received ids in your system so duplicates are no-ops.