Change notifications (webhooks)
How another system learns that a ride changed without constantly asking — and how it checks the message really came from us.
To know that a ride changed, another system could keep asking — but that is like calling the dispatcher every five minutes. A webhook is the other way round: the platform says something when something actually happens.
Events
| Event | When it is sent |
|---|---|
ride.created | A ride was created — from the console, the API or the passenger app |
ride.updated | Every ride status change; the only event that receives each and every change |
ride.completed | The ride finished; the final price is in the detail |
ride.cancelled | The ride was cancelled or the passenger did not show up (NO_SHOW) |
{
"id": "evt_9f2c1a446b0b4a1e8d5c",
"type": "ride.completed",
"createdAt": "2026-11-17T08:29:12.004Z",
"company": { "slug": "taxi-a", "displayName": "DEMO-TAXI" },
"data": {
"number": "R-2026-000417",
"status": "COMPLETED",
"channel": "API",
"externalId": "erp-2026-000417",
"completedAt": "2026-11-17T08:29:00.000Z",
"finalPrice": 24.30,
"currencyCode": "EUR",
"driver": { "code": "D-014", "name": "Ivo Ivić" }
}
}
id; without it, use type plus data.number and createdAt.Signature: proving the request is ours
Every request carries the X-Whitelabel-Signature header as t=<unix>,v1=<hmac>. The signature is HMAC-SHA256 over <timestamp>.<body>. The secret is 32 random bytes and is shown in the console when the webhook is created.
Verification has three steps: the header shape, the freshness of the timestamp (300 seconds) and a constant-time comparison. Skipping the freshness check lets a replayed request through; skipping the constant-time comparison leaks timing information.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, header, secret, toleranceSeconds = 300) {
const parts = String(header || '').split(',').map((part) => part.trim());
const t = parts.find((part) => part.startsWith('t='));
const v1 = parts.find((part) => part.startsWith('v1='));
if (!t || !v1) return false;
const timestamp = Number.parseInt(t.slice(2), 10);
const provided = v1.slice(3);
if (!Number.isFinite(timestamp)) return false;
if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
const left = Buffer.from(expected, 'hex');
const right = Buffer.from(provided, 'hex');
return left.length === right.length && timingSafeEqual(left, right);
}function verify(string $rawBody, string $header, string $secret, int $tolerance = 300): bool
{
$parts = [];
foreach (explode(',', $header) as $part) {
$pair = array_pad(explode('=', trim($part), 2), 2, '');
$parts[$pair[0]] = $pair[1];
}
if (!isset($parts['t'], $parts['v1'])) return false;
if (abs(time() - (int) $parts['t']) > $tolerance) return false;
$expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
return hash_equals($expected, $parts['v1']);
}import hashlib, hmac, time
def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(part.strip().split('=', 1) for part in header.split(',') if '=' in part)
timestamp, provided = parts.get('t'), parts.get('v1')
if not timestamp or not provided:
return False
if abs(time.time() - int(timestamp)) > tolerance:
return False
expected = hmac.new(secret.encode(), f'{timestamp}.'.encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, provided)express.raw, not express.json.Retries and the dead letter
| Rule | Value |
|---|---|
| Success | Any 2xx response within 8 seconds |
| Maximum attempts | 5 |
| Delays | 5 s, 30 s, 2 min, 10 min — the fifth failure is a dead letter |
| Order | Deliveries are sent in batches of up to 50; per-event ordering is not guaranteed, so rely on createdAt |
| Security | Private addresses (localhost, 127.0.0.1) and addresses with a user/password are rejected |
Delivery monitoring over the API
Webhook health: endpoints, delivery counts per status and the last attempt. Scope webhooks.
{
"endpoints": [
{
"id": "1a2b3c4d-…",
"url": "https://erp.taxi-a.hr/webhooks/driveos",
"events": ["ride.created", "ride.updated", "ride.completed", "ride.cancelled"],
"isActive": true,
"createdAt": "2026-10-02T09:00:00.000Z",
"deliveries": { "DELIVERED": 1841, "PENDING": 2, "DEAD": 0 },
"lastDeliveryAt": "2026-11-17T08:29:13.000Z"
},
{
"id": "5e6f7a8b-…",
"url": "https://stara-adresa.taxi-a.hr/hook",
"events": ["ride.updated"],
"isActive": false,
"deliveries": { "DELIVERED": 12, "PENDING": 0, "DEAD": 5 },
"lastDeliveryAt": "2026-11-02T14:10:44.000Z"
}
]
}
If DEAD is greater than zero the endpoint returned errors for more than 12 minutes and events were dropped. The company console shows the same figure and allows resending with a manual trigger.

