Webhooks

Inbound webhook security

Webhook endpoints authenticate the exact raw request bytes before parsing. Each provider adapter declares its signature headers, timestamp encoding, digest algorithm, and replay window. A valid signature is necessary but not sufficient: endpoint state, provider identity, event ID, timestamp skew, and body-size limits are also checked.

Persisted receipts are deduplicated by endpoint/provider event identity, then processed durably. 2xx means the receipt was authenticated and accepted—not that every downstream projection already changed. Invalid signatures and oversized or stale requests are rejected without disclosing which secret or endpoint attribute failed.

Generic HMAC example

Use the provider-specific guide when available. This pseudocode illustrates the required constant-time comparison over timestamp plus raw bytes.

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

function verify(secret: Uint8Array, timestamp: string, rawBody: Uint8Array, suppliedHex: string) {
  const expected = createHmac("sha256", secret)
    .update(timestamp)
    .update(".")
    .update(rawBody)
    .digest();
  const supplied = Buffer.from(suppliedHex, "hex");
  return supplied.length === expected.length && timingSafeEqual(supplied, expected);
}

Never reconstruct JSON before verification. Reject timestamp skew before expensive work. Keep at least two credentials during rotation, label versions, and revoke the old version only after delivery traffic moves.

Delivery and replay

Outbound business webhooks use signed, bounded payloads and durable attempts with exponential backoff, jitter, circuit breaking, and a terminal dead-letter state. Consumers must deduplicate on event ID. A manual replay creates an auditable delivery attempt; it never mutates the original event.

Do not treat inbound analytics, economic, custody, or security claims as authoritative simply because they arrived through a webhook. The appropriate domain worker verifies provider or chain evidence before projection.