Webhooks

Credits ran out

Sent once when the balance reaches zero and requests are being refused with 402 no_credits. Checked hourly.

Answer with any 2xx within 10 seconds, then do the work. Anything else (including a redirect) is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h; after 8 attempts the event is given up. Order is not guaranteed.

postWebhookcredits.depleted

Headers

NameGender-Signaturestring required
Example:t=1727172264,v1=857fcddfea47617c448b7a8e6537bbd59c9922a37c5273b2709812fbadb29e50

t=<unix seconds>,v1=<hex>. v1 is HMAC-SHA256 of "<t>.<raw body>" with the endpoint secret. During a secret rotation a second v1 is present for 24 hours; accept the request if any v1 matches. Reject a t more than 5 minutes from your clock.

NameGender-Event-Idstring required
Example:evt_16f7c01502fda5436e8b7c4e

Same as id in the body, and the same on every retry. Deduplicate on it.

NameGender-Delivery-Attemptinteger required

1 on the first try, then 2, 3… up to 8.

Payload

idstring required

Event id; stable across retries.

type'credits.depleted' required

New types can be added. Answer 2xx to a type you do not recognise and ignore it.

created_atstring date-time required
api_version'v1' required

Example payload

{
  "id": "evt_16f7c01502fda5436e8b7c4e"
}

Response

Received. Any 2xx status counts; the body is ignored.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.