loom-webhooks

Webhooks

Overview

HTTP callbacks that push events to external systems instead of polling. The hard parts are all correctness/security: signing over the right bytes, timing-safe verification, replay protection, at-least-once delivery + idempotent consumers, and SSRF on the sender. This skill is organized sender-side vs receiver-side, with the traps called out.

The non-negotiables (read first)

• Sign/verify over the RAW request body, not re-serialized JSON. JSON.parse → JSON.stringify reorders keys and changes whitespace, breaking the HMAC. Receiver must read raw bytes before any JSON body parser runs.
• Timing-safe compare for signatures — never ===. And guard length first: crypto.timingSafeEqual throws on unequal-length buffers.
• Timestamped signatures + a tolerance window to blunt replay; dedup by event id for the rest.
• At-least-once delivery is the only realistic guarantee ⇒ duplicates will arrive ⇒ consumers must be idempotent.
• Verify before you trust or parse. For security-critical actions, treat the payload as a hint and refetch canonical state from your API.
• Sender makes outbound requests to user-supplied URLs ⇒ SSRF surface. Validate destinations; block internal ranges.

Event & subscription model

interface WebhookEvent {
  id: string;            // stable, unique → idempotency + replay key
  type: string;          // "order.created" — resource.action
  created: number;       // Unix seconds
  apiVersion: string;    // payload schema version
  data: {
    object: Record<string, unknown>;
    previousAttributes?: Record<string, unknown>; // deltas on updates
  };
}

interface WebhookEndpoint {
  id: string;
  url: string;
  secret: string;        // per-endpoint, rotatable
  events: string[];      // ["order.*", "payment.completed", "*"]
  status: "active" | "disabled";
}

Naming: resource.action (order.created, payment.failed). Support wildcards (order.*, *).

Thin vs fat events (design decision)