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đaj | Kada se šalje |
|---|---|
ride.created | Vožnja je naručena — iz konzole, API-ja ili putničke aplikacije |
ride.updated | Svaka promjena stanja vožnje; jedini događaj koji dobiva baš svaku promjenu |
ride.completed | Vožnja je završena; konačna cijena je u detalju |
ride.cancelled | Vožnja je otkazana ili putnik nije došao (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 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);
}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, ne express.json.Ponovni pokušaji i mrtvo slovo
| Pravilo | Vrijednost |
|---|---|
| Uspjeh | Bilo koji odgovor 2xx u roku od 8 sekundi |
| Najviše pokušaja | 5 |
| Razmaci | 5 s, 30 s, 2 min, 10 min — peti promašaj je mrtvo slovo |
| Redoslijed | Dostave se šalju u serijama do 50; redoslijed po događaju nije zajamčen, pa se oslonite na createdAt |
| Sigurnost | Privatne adrese (localhost, 127.0.0.1) i adrese s korisnikom/lozinkom se odbijaju |
Nadzor dostava preko API-ja
Zdravlje webhookova: krajnje točke, broj dostava po statusu i zadnji pokušaj. Opseg 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"
}
]
}
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.

