Webhooks
A webhook is an HTTPS endpoint on your side that Herd posts to when something happens.
Register an endpoint
Section titled “Register an endpoint”- In the console, open Settings and find Webhooks.
- Enter your URL and tick the events you want.
- Copy the signing secret. It starts with
whsec_and is shown once. - Use Test to post a
pingand check your endpoint answers2xx.
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.
Events
Section titled “Events”| 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.
Payload
Section titled “Payload”{ "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> |
Verify the signature
Section titled “Verify the signature”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.
Retries
Section titled “Retries”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.