Driveosplatform catalogue

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

EventWhen it is sent
ride.createdA ride was created — from the console, the API or the passenger app
ride.updatedEvery ride status change; the only event that receives each and every change
ride.completedThe ride finished; the final price is in the detail
ride.cancelledThe ride was cancelled or the passenger did not show up (NO_SHOW)
jsontijelo zahtjeva — `ride.completed`
{
  "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ć" }
  }
}
Idempotency on your sideThe same event can arrive twice (a retry after a timeout). The key for discarding duplicates is the event 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);
}
The body must be exactly what arrivedThe signature is computed over the raw body. If you parse and re-serialise it, spacing and key order change and the signature no longer matches. In Express use express.raw, not express.json.

Retries and the dead letter

RuleValue
SuccessAny 2xx response within 8 seconds
Maximum attempts5
Delays5 s, 30 s, 2 min, 10 min — the fifth failure is a dead letter
OrderDeliveries are sent in batches of up to 50; per-event ordering is not guaranteed, so rely on createdAt
SecurityPrivate addresses (localhost, 127.0.0.1) and addresses with a user/password are rejected

Delivery monitoring over the API

GET/api/v1/webhooks

Webhook health: endpoints, delivery counts per status and the last attempt. Scope webhooks.

json200 — zdrava točka i točka koja pada
{
  "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.

Light themeDark theme
Company → Developer: webhook addresses, events and the last delivery.