Signed webhooks

Payloads carry ids, dates, cities, statuses and the names of your own travelers. They never carry notes, purposes, email addresses, phone numbers, passport, loyalty or payment details: look those up in the portal. Every field of every event is in the OpenAPI document.

1. Read the raw request body before parsing it, and the silentVIP-Signature header. Split the header on commas into t and v1.

2. Compute HMAC-SHA256 of t, a period and the raw body, with the whole signing secret (including whsec_) as the key, as UTF-8. Hex-encode it.

3. Compare it with v1 in constant time, and refuse a t more than five minutes from now, so an old delivery can't be replayed.

Node.js

import crypto from "node:crypto";

// rawBody: the request body exactly as received (a string, before any JSON parsing)
// header: the silentVIP-Signature header; secret: the endpoint's signing secret, from your secret store
export function verifySilentvip(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(String(header || "").split(",").map((p) => p.trim().split("=")));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret).update(t + "." + rawBody).digest();
  const given = Buffer.from(String(parts.v1 || ""), "hex");
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

Python

import hashlib, hmac, time

# raw_body: the request body as bytes, exactly as received; header: the silentVIP-Signature header
def verify_silentvip(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    try:
        parts = dict(p.strip().split("=", 1) for p in header.split(","))
        t = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), str(t).encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Never put the secret in source code: read it from your secret store. If it may have leaked, rotate it in the portal; deliveries use the new secret at once.