Webhooks

A file job failed

data.object is the job with status: failed; branch on error.code. A failed job is not charged.

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.

postWebhookbatch.failed

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'batch.failed' 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",
  "data": {
    "object": {
      "id": "B-7K2M9QX4TA"
    }
  }
}

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.