Skip to main content
Webhooks push events to your server the moment something changes — a shipment is delivered, a payment settles, a return is refunded. Subscribe an endpoint to the events you care about and verify each delivery’s signature.

Subscribe an endpoint

Event types

Event payload

Every event uses the same envelope:
  • livemode — true for production, false for sandbox (test) events. Key your handler off this so a test event never triggers live logic.
  • api_version — the schema version, so you can evolve safely.
  • data.object — a minimal summary (ids + key fields). Call the REST API for the full record if you need more.

Verify the signature

Each delivery carries a TLDP-Signature header of the form t=<timestamp>,v1=<hex>. Recompute the HMAC-SHA256 of `${timestamp}.${rawBody}` with your endpoint’s signing secret and compare.
Verify the signature on the raw request body before parsing JSON. Reject any request that fails verification.

Reliability

  • Retries — a non-2xx response is retried with exponential backoff. Respond 2xx quickly (do heavy work asynchronously).
  • Idempotency — deduplicate on event.id; the same event may arrive more than once.
  • Auto-disable — an endpoint that fails repeatedly is disabled to stop pointless retries. Re-enable it once it’s healthy.

Test it

Send yourself a realistic sample event (marked test: true, livemode: false):