Subscribe an endpoint
Event types
Event payload
Every event uses the same envelope:livemode—truefor production,falsefor 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 aTLDP-Signature header of the form t=<timestamp>,v1=<hex>.
Recompute the HMAC-SHA256 of `${timestamp}.${rawBody}` with your endpoint’s
signing secret and compare.
Reliability
- Retries — a non-2xx response is retried with exponential backoff. Respond
2xxquickly (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 (markedtest: true, livemode: false):

