Driveoskatalog platforme

Obavijesti o promjenama (webhookovi)

Kako drugi program sazna da se vožnja promijenila, a da ne mora stalno pitati — i kako provjeri da je poruka stvarno naša.

Da bi drugi program znao da se vožnja promijenila, može stalno pitati — ali to je kao da svakih pet minuta zovete dispečera. Webhook je obrnuto: platforma javi kad se nešto stvarno dogodi.

Događaji

DogađajKada se šalje
ride.createdVožnja je naručena — iz konzole, API-ja ili putničke aplikacije
ride.updatedSvaka promjena stanja vožnje; jedini događaj koji dobiva baš svaku promjenu
ride.completedVožnja je završena; konačna cijena je u detalju
ride.cancelledVožnja je otkazana ili putnik nije došao (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ć" }
  }
}
Idempotencija na vašoj straniIsti događaj može stići dvaput (ponovni pokušaj nakon vremenske odsječenosti). Ključ za odbacivanje duplikata je id događaja; ako ga nemate, koristite kombinaciju type i data.number uz createdAt.

Potpis: kako dokazati da je zahtjev naš

Svaki zahtjev nosi zaglavlje X-Whitelabel-Signature u obliku t=<unix>,v1=<hmac>. Potpis je HMAC-SHA256 nad nizom tijelo s prefiksom vremena: vrijeme.tijelo. Tajna ima 32 slučajna bajta i vidljiva je u konzoli pri stvaranju webhooka.

Provjera ima tri koraka: oblik zaglavlja, svježina vremena (300 sekundi) i usporedba potpisa u konstantnom vremenu. Preskakanje provjere svježine pušta ponovno odaslani zahtjev; preskakanje usporedbe u konstantnom vremenu pušta mjerenje vremena.

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);
}
Tijelo mora biti točno ono što je stigloPotpis se računa nad sirovim tijelom. Ako ga parsirate pa ponovno serijalizirate, razmak i redoslijed ključeva se mijenjaju i potpis više ne vrijedi. U Expressu koristite express.raw, ne express.json.

Ponovni pokušaji i mrtvo slovo

PraviloVrijednost
UspjehBilo koji odgovor 2xx u roku od 8 sekundi
Najviše pokušaja5
Razmaci5 s, 30 s, 2 min, 10 min — peti promašaj je mrtvo slovo
RedoslijedDostave se šalju u serijama do 50; redoslijed po događaju nije zajamčen, pa se oslonite na createdAt
SigurnostPrivatne adrese (localhost, 127.0.0.1) i adrese s korisnikom/lozinkom se odbijaju

Nadzor dostava preko API-ja

GET/api/v1/webhooks

Zdravlje webhookova: krajnje točke, broj dostava po statusu i zadnji pokušaj. Opseg 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"
    }
  ]
}

Ako je broj DEAD veći od nule, krajnja točka je primala greške dulje od 12 minuta i događaji su odbačeni. Konzola tvrtke pokazuje isti podatak i omogućuje ponovno slanje ručnim pokretanjem.

Svjetla temaTamna tema
Tvrtka → Razvoj: adrese webhookova, događaji i zadnja dostava.