@tickbird/webhooks

The Tickbird webhook contract — the single source of truth for the event catalog, typed payloads, and HMAC sign/verify. The Tickbird server produces deliveries with it, and @tickbird/sdk re-exports it, so the definitions on both ends cannot drift.

Most consumers should use @tickbird/sdk (its /webhooks entry re-exports everything here). Install this package directly only if you want webhook verification with no API client.

npm install @tickbird/webhooks

import { constructEvent } from "@tickbird/webhooks";

// Pass the RAW request body — re-serialized JSON breaks the signature.
const event = await constructEvent({
  body: rawBody,
  headers: request.headers, // a Headers instance or a plain record
  secret: process.env.TICKBIRD_WEBHOOK_SECRET!, // whsec_…
});

switch (event.type) {
  case "timer.committed":
    event.data.totalSeconds; // number — narrowed by event.type
    break;
}

constructEvent verifies the Tickbird-Signature (HMAC-SHA256, v1=<hex>) and rejects replays outside a 300s tolerance (configurable), throwing WebhookSignatureVerificationError on failure. Lower-level verify(...) returns a boolean; sign(...) is the server-side counterpart. Runs anywhere with Web Crypto: Node 18+, Cloudflare Workers, Deno, Bun, browsers.

Subpath exports: @tickbird/webhooks/events, /types, /crypto.