Webhook event delivery
Verify, dedupe, inspect, replay, and test 0Gate webhook delivery before updating durable partner state.
0Gate sends signed webhook events to your configured webhook URL. Your backend should verify Gate-Signature against the raw request body, reject invalid or stale signatures, dedupe by event id, and make the side effect idempotent.
Delivery model
Verification checklist
| Step | Requirement |
|---|---|
| Raw body | Verify the raw request bytes, not a re-stringified JSON object. |
| Header | Read Gate-Signature in the t=<timestamp>,v1=<hex> format. |
| Tolerance | Reject stale timestamps. The SDK helper defaults to a 300 second tolerance. |
| HMAC | Compute HMAC-SHA256 over <timestamp>.<rawBody> using your webhook secret. |
| Constant-time compare | Compare expected and received signatures without timing leaks. |
| Dedupe | Store and check event id before side effects. |
| Acknowledge | Return a 2xx after successful durable processing or duplicate recognition. |
const event = gate.webhooks.constructEvent(
rawBody,
request.headers['gate-signature'],
process.env.WEBHOOK_SECRET,
);
await processGateEventIdempotently(event);Delivery operations
| Operation | Use |
|---|---|
| List deliveries | Inspect status, attempts, target URL, last response status, and last error for your account. |
| Replay delivery | Re-queue a dead-lettered delivery after your handler is fixed. |
| Send test event | Verify endpoint reachability and signature handling without a real session event. |
The delivery log intentionally omits raw payload bodies. It is for delivery health, not payload inspection.
Retry behavior is operational, not an SLA
The current backend retries transient failures with backoff and dead-letters persistent failures. Treat exact retry timing as operational behavior unless your partner agreement states a contractual delivery SLA.