Webhooks

Event delivery

Batchrouter delivers signed JSON events to your endpoint with retries and exponential backoff.

Get an API key API reference

Signed

HMAC

X-Batchrouter-Signature

Retries

8×

exponential backoff over 24h

Ack window

10s

process async after 2xx

Delivery

POST · application/json

Events are POSTed as JSON with an X-Batchrouter-Signature header. We retry non-2xx responses up to 8 times over 24 hours with exponential backoff. Respond quickly (within 10s) and process asynchronously.

Example payload

batch.completed

event.json

{
  "id": "evt_01HW...",
  "type": "batch.completed",
  "created": 1730000000,
  "data": {
    "batch_id": "batch_123",
    "status": "completed",
    "items_total": 1000,
    "items_completed": 998,
    "items_failed": 2,
    "cost_usd": "2.4137",
    "output_file_url": "https://artifacts.batchrouter.dev/..."
  }
}

Event types

batch.quoted
A new quote is ready. Payload includes quote_id, expires_at, and per-lane prices.
batch.submitted
A batch has been accepted and is now routing.
batch.progress
Periodic progress with completed/failed counts. Sent at most every 30 seconds.
batch.completed
Terminal success. Payload includes output_file_url, totals, and final cost.
batch.failed
Terminal failure. Payload includes error code and a partial output URL if any.

Pair webhooks with the quickstart

Submit a batch, then verify your endpoint receives a signed completion event.

← Back to docs Quickstart