Webhooks

​

Event catalogue

​

Event envelope

{
  "id": "8c3f9a40-3b5d-4d52-9a2e-cc1f4b7d8e2a",
  "type": "booking.confirmed",
  "created_at": "2026-07-12T10:05:00Z",
  "test": false,
  "data": { "booking_number": "MV-AB7X92", "partner_reference": "YBANK-BOOK-001" }
}

• id — idempotent event ID. Deduplicate on it (the same event may be delivered more than once).
• test — true when the event comes from an sk_test_* key or from POST /webhooks/{id}/test. Your production handler must ignore or clearly label these.

​

Delivery headers

​

Verifying the signature

import crypto from 'node:crypto';

function verify(rawBody, header, signingSecret) {
  const expected = crypto.createHmac('sha256', signingSecret)
    .update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

import hmac, hashlib

def verify(raw_body: bytes, header: str, signing_secret: str) -> bool:
    expected = hmac.new(signing_secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

​

Retries

​

Delivery semantics

• Deduplicate. The same event (X-SafarApi-Event-Id) may be delivered more than once — on retry, and in a narrow window if a delivery is received but our status write is interrupted. Treat the first successful processing as authoritative and make re-processing a no-op (upsert / dedup table keyed by Event-Id).
• Do not rely on ordering. Events are dispatched concurrently and retried with backoff, so they can arrive out of order (e.g. booking.cancelled before its booking.confirmed, or a retried event after a newer one). Drive your state from the event’s created_at and your own state machine — never assume the arrival order reflects the real sequence.

​

Testing