Webhooks Overview - Bodha Route Planner

Webhooks let your server receive HTTP POST requests whenever something happens in your Bodha account — a route is dispatched, a stop is completed, an order is created, and more.

How it works

You register an HTTPS endpoint in the Developer Portal (Settings → Developer).
You choose which events to subscribe to.
When an event fires, Bodha sends a JSON POST to your endpoint with the event payload, signed with HMAC-SHA256 so you can verify authenticity.

Endpoint requirements

Requirement	Detail
Protocol	HTTPS only — HTTP endpoints are rejected
Response	Return `2xx` within 10 seconds
Idempotency	You may receive the same event more than once — use the delivery `id` to deduplicate

Delivery & retries

Each delivery is recorded with its HTTP status, response body (first 4 KB), and duration. If your endpoint returns a non-2xx status or times out:

The delivery is marked as failed.
The endpoint’s failureCount increments.
After 10 consecutive failures, the endpoint is automatically disabled.
You can retry any delivery manually from the Developer Portal or via the API.

Bodha does not automatically retry failed deliveries. Use the retry endpoint or the Developer Portal to replay a delivery.

Payload shape

Every webhook POST has this structure:

{
  "event": "route.dispatched",
  "timestamp": "2026-10-28T14:30:00.000Z",
  "data": {
    "id": "665f1a2b3c4d5e6f7a8b9c0d",
    "name": "North Bay Deliveries",
    "status": "dispatched",
    ...
  }
}

Security headers

Header	Value
`Content-Type`	`application/json`
`X-Bodha-Signature`	HMAC-SHA256 hex digest of the raw body
`X-Bodha-Event`	The event name (e.g. `route.dispatched`)
`User-Agent`	`Bodha-Webhooks/1.0`

See Verifying Signatures for verification code in multiple languages.