API Reference
Webhooks overview
Receive signed payment session and transaction notifications.
When to use webhooks
Use webhooks to confirm payment outcomes without polling. Treat payment_session.completed and related transaction events as the primary async signal for order fulfillment. The Checkout SDK callbacks cover the browser experience; webhooks cover server-side reconciliation.
Security model
- HTTPS endpoints only.
- Signing secret
whsec_...shown once at registration. X-Zippy-Signature: sha256=<hex>over the exact raw JSON body (not Stripe t=,v1=).- Also receive
X-Zippy-Webhook-IdandX-Zippy-Delivery-Id.
Register an endpoint
Register endpoints in the merchant portal at zippypay.io (Developer → Webhooks). All active endpoints receive every live event for your business. See manage endpoints.
Delivery flow
Payment event
Session or transaction changes
Event queue
Event is recorded
signed POST
Delivery attempt
POST to your endpoint
response
2xx · Accepted
Failure · Inspect & resend
Delivery is best-effort. Resend failed deliveries manually from the portal.
Receiver checklist
- Idempotent handlers keyed by envelope
id,X-Zippy-Webhook-Id, orX-Zippy-Delivery-Id. - Raw body signature verification.
- Branch on
data._test === truefor portal test deliveries. - Respond quickly within the 10-second default timeout.