Skip to content

Webhooks

A webhook is an HTTPS endpoint on your side that Herd posts to when something happens.

  1. In the console, open Settings and find Webhooks.
  2. Enter your URL and tick the events you want.
  3. Copy the signing secret. It starts with whsec_ and is shown once.
  4. Use Test to post a ping and check your endpoint answers 2xx.

Managing webhooks needs the Admin role. Log on each endpoint shows every delivery and its status. Edit has an Active switch to pause an endpoint without deleting it.

Event Sent when data fields
ride.started A rider unlocks a bike rental_id, vehicle_id, started_at
ride.ended A ride is closed and priced rental_id, vehicle_id, started_at, ended_at, duration_s, fare_cents, ended_in_hub
vehicle.status_changed A bike enters or leaves shop mode or rebalancing vehicle_id, field, value, ops_state
ping You press Test message

vehicle.status_changed covers those two modes only. It does not fire for battery level, going offline or being rented.

{
"id": "evt_…",
"type": "ride.ended",
"created_at": "2026-05-01T14:03:22Z",
"data": {
"rental_id": "…",
"vehicle_id": "…",
"started_at": "2026-05-01T13:41:10Z",
"ended_at": "2026-05-01T14:03:20Z",
"duration_s": 1330,
"fare_cents": 350,
"ended_in_hub": true
}
}

Each request also carries these headers:

Header Value
X-Herd-Event The event type
X-Herd-Event-Id The event’s id, the same on every retry
X-Herd-Delivery An id for this delivery. Use it to ignore duplicates
X-Herd-Signature t=<unix time>,v1=<hex>

Compute an HMAC-SHA256 of <t>.<raw request body> with your signing secret and compare it with v1. Reject requests whose t is more than five minutes old.

import hashlib, hmac, time
def verify(secret: str, header: str, body: bytes) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(parts["t"])) > 300:
return False
signed = parts["t"].encode() + b"." + body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])

Verify against the raw bytes you received, before any JSON parsing.

Anything other than a 2xx within 10 seconds counts as a failure. Herd tries five times in all: at once, then after 10 seconds, 1 minute, 5 minutes and 30 minutes. After that the delivery is marked failed in the log.

Deliveries are best effort. A retry that is waiting can be lost if Herd restarts, so do not treat webhooks as your only record. Reconcile against GET /rides on a schedule.