POST to your webhook URL when a checkout session reaches a final state. Use webhooks to fulfill orders instead of relying on the customer’s redirect.
Prerequisites
- A Warp project with a public HTTPS endpoint that can receive
POSTrequests. - In the Warp Platform, open your project’s settings, set the webhook URL and copy the signing secret. Store the secret on your server, for example as
WARP_WEBHOOK_SECRET.
Webhook URLs must be publicly reachable. Warp does not deliver to private, loopback or link-local addresses.
Events
Request format
Each delivery has these headers:
The body wraps the checkout session object:
Verify the signature
v1 is the hex-encoded HMAC-SHA256 of <t>.<raw request body>, keyed with your signing secret. To verify a delivery:
- Read the raw request body. Don’t parse and re-serialize the JSON first.
- Split
Warp-Signatureon,and readtandv1. - Compute the HMAC of
`${t}.${rawBody}`with your secret and compare it tov1in constant time. - Reject the event if
tis more than a few minutes from your server’s clock, to limit replay.
Example
Delivery and retries
- Respond with a
2xxstatus within 10 seconds. Do slow work (emails, fulfillment jobs) after you respond or in a background job. - Any other response, a timeout or a connection error counts as a failure. Warp retries after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours. After the last attempt the delivery is marked failed.
- The same event can arrive more than once, and events can arrive out of order. Deduplicate by event ID (
Warp-Event-Idorid) and, when in doubt, retrieve the session for its currentstatus.
Next steps
Quickstart
Create a session and take a test payment.
Retrieve a checkout session
Check a session’s current status from your server.