Shipment webhooks

{
  "schemaVersion": "1",
  "eventId": "694f46e7-4a4e-43a1-a095-516f52ec2141",
  "eventType": "shipment.status_changed",
  "emittedAt": "2026-07-28T10:42:18.000Z",
  "data": {
    "shipmentId": 12345,
    "fileReference": "BB-ABCD-3",
    "status": "in_progress"
  }
}

<timestamp>.<eventId>.<mode>.<rawBody>

import { createHmac, timingSafeEqual } from "node:crypto";
import { z } from "zod";

const payloadSchema = z.object({
  schemaVersion: z.literal("1"),
  eventId: z.string().uuid(),
  eventType: z.literal("shipment.status_changed"),
  emittedAt: z.string().datetime(),
  data: z.object({
    shipmentId: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
    fileReference: z.string().min(1),
    status: z.enum([
      "booking_request", "awaiting_booking", "booked", "in_progress",
      "arrived", "finished", "cancelled",
    ]),
  }).strict(),
}).strict();

const parseWebhookHeaders = ({ headers, nowSeconds }) => {
  const signed = z.object({
    eventId: z.string().uuid(),
    timestamp: z.string().regex(/^(0|[1-9][0-9]*)$/),
    mode: z.enum(["live", "test"]),
    signature: z.string().regex(/^v1=[0-9a-f]{64}$/),
  }).parse({
    eventId: headers.get("X-Ovrsea-Webhook-Id"),
    timestamp: headers.get("X-Ovrsea-Webhook-Timestamp"),
    mode: headers.get("X-Ovrsea-Webhook-Mode"),
    signature: headers.get("X-Ovrsea-Webhook-Signature"),
  });
  const timestampSeconds = Number(signed.timestamp);
  if (!Number.isSafeInteger(timestampSeconds) ||
      !Number.isSafeInteger(nowSeconds) ||
      Math.abs(nowSeconds - timestampSeconds) > 300) {
    throw new Error("Webhook timestamp outside receiver tolerance");
  }
  return signed;
};

const verifyWebhookSignature = ({ signed, rawBody, signingSecret }) => {
  if (!Buffer.isBuffer(rawBody) ||
      typeof signingSecret !== "string" || signingSecret.trim().length === 0) {
    throw new Error("Raw bytes and a signing secret are required");
  }
  const { timestamp, eventId, mode, signature } = signed;
  const expected = createHmac("sha256", Buffer.from(signingSecret, "utf8"))
    .update(`${timestamp}.${eventId}.${mode}.`, "utf8")
    .update(rawBody)
    .digest();
  const received = Buffer.from(signature.slice(3), "hex");
  if (received.length !== expected.length ||
      !timingSafeEqual(received, expected)) {
    throw new Error("Invalid webhook signature");
  }
};

const parseWebhookPayload = ({ rawBody, eventId }) => {
  const text = new TextDecoder("utf-8", { fatal: true }).decode(rawBody);
  const payload = payloadSchema.parse(JSON.parse(text));
  if (payload.eventId !== eventId) {
    throw new Error("Webhook event ID mismatch");
  }
  return payload;
};

export const verifyShipmentWebhook = ({
  headers,
  rawBody,
  signingSecret,
  nowSeconds = Math.floor(Date.now() / 1000),
}) => {
  const signed = parseWebhookHeaders({ headers, nowSeconds });
  verifyWebhookSignature({ signed, rawBody, signingSecret });
  const payload = parseWebhookPayload({ rawBody, eventId: signed.eventId });
  return { mode: signed.mode, payload };
};