Skip to main content
Warp sends an HTTPS 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 POST requests.
  • 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:
  1. Read the raw request body. Don’t parse and re-serialize the JSON first.
  2. Split Warp-Signature on , and read t and v1.
  3. Compute the HMAC of `${t}.${rawBody}` with your secret and compare it to v1 in constant time.
  4. Reject the event if t is more than a few minutes from your server’s clock, to limit replay.

Example

Delivery and retries

  • Respond with a 2xx status 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-Id or id) and, when in doubt, retrieve the session for its current status.

Next steps

Quickstart

Create a session and take a test payment.

Retrieve a checkout session

Check a session’s current status from your server.