Webhooks - signed endpoints and the event catalogue

Signed, at-least-once webhook delivery from a durable outbox. There are two delivery paths:

later): the owner registers endpoints with an event filter; every delivery carries a Dynamo-Signature header. This is the path to use. Status: Live.

through the merchant API; deliveries carry x-dynamo-signature. A subscription receives only events about its own service node; described at the end of this page.

The schemas are versioned artifacts: the supported envelope versions are 1.0.0 to 1.6.0. Each event type rides the schema version it was added in, byte for byte; additive changes bump the minor version with a CHANGELOG entry, and breaking changes require a written deprecation note.

The contract in one paragraph

Every event carries a stable event id (your idempotency key), a schema version, a stable externalRef for correlation, and - where money is involved - the settled amount asset-denominated plus an asset label (R7). Delivery is AT-LEAST-ONCE: you WILL see duplicates and you MAY see reordering; dedupe on the event id and treat settlement amounts as cumulative monotone values (R1/R3). Credit on settlement.final only (R2) - settlement.checkpointed is a visible pending state, never a credit signal. Verify the signature before touching state; reject on mismatch.

Allowed targets

Both delivery paths accept only an https URL on a public address. A URL with credentials or a fragment, localhost, or a loopback, private, link-local or reserved address (including IPv4-mapped IPv6 and numeric IPv4 forms) is refused with 400 when you register it, and checked again before every delivery. Each delivery resolves the host once and connects to that checked address, follows no redirect (a 3xx is a failed attempt), gives up after 10 seconds and reads at most 64 KiB of the answer.

A self-hosted core can let webhooks reach http, loopback and private targets for local development only through a setting made in code (allowPrivateWebhookTargets), never through the environment; it logs a warning at boot. The hosted (multi-tenant) service refuses it.

Signed webhook endpoints

RouteWhat it does
POST /owner/v1/webhooks/endpoints{url, events} → {endpoint, secret}; the whsec_… secret is shown once
GET /owner/v1/webhooks/endpointsthe endpoints, one page {data, next_cursor} (limit 1 to 100); secrets are never listed
DELETE /owner/v1/webhooks/endpoints/{id}delete an endpoint; its pending deliveries are cancelled
POST /owner/v1/webhooks/endpoints/{id}/rotatea new secret, shown once; the old one keeps signing for a 24-hour overlap
POST /owner/v1/webhooks/endpoints/{id}/replay{since} (re-sends up to 1000 events) or {eventIds} (1 to 100 ids): re-send stored events with their original ids
GET /owner/v1/events/catalogueevery event type, its schema version and its data fields; clients pinned at 1.8.0 get the 1.6.0 edition

Every delivery carries:

the whole secret string as the key over <t>. followed by the exact raw body. During a rotation overlap the header carries one v1= per live secret; accept the delivery when any one matches.

A failed delivery is retried with exponential backoff (10 seconds doubling, at most one hour apart) for up to 72 hours, then parked as failed, never dropped silently; the core logs it and, when the operator has set alert email (CORE_SMTP_HOST, CORE_ALERT_EMAIL_TO), emails that address. A replay re-sends the same event ids, so your dedupe still holds.

On a single-tenant core the endpoint routes need an events database (EVENTS_DB); without one they answer 409.

This sample is the complete check, with a 300-second tolerance on t:

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

function verifyDynamoSignature(secret: string, rawBody: string, header: string, nowSeconds: number): boolean {
  const parts = header.split(",").map((p) => p.split("="));
  const t = parts.find(([k]) => k === "t")?.[1];
  const v1s = parts.filter(([k]) => k === "v1").map(([, v]) => v ?? "");
  if (t === undefined || !/^\d+$/.test(t) || v1s.length === 0) return false;
  if (Math.abs(nowSeconds - Number(t)) > 300) return false;
  const expected = Buffer.from(createHmac("sha256", secret).update(`${t}.${rawBody}`, "utf8").digest("hex"));
  return v1s.some((v) => {
    const got = Buffer.from(v);
    return got.length === expected.length && timingSafeEqual(got, expected);
  });
}

const secret = "whsec_example_docs_secret_0123456789abcdef";
const body = JSON.stringify({ id: "evt_0123456789abcdef01234567", type: "settlement.final", data: {} });
const now = Math.floor(Date.now() / 1000);
const header = `t=${now},v1=${createHmac("sha256", secret).update(`${now}.${body}`, "utf8").digest("hex")}`;

if (!verifyDynamoSignature(secret, body, header, now)) throw new Error("valid signature must verify");
if (verifyDynamoSignature(secret, body.replace("final", "FINAL"), header, now)) {
  throw new Error("a tampered body must be rejected");
}
if (verifyDynamoSignature(secret, body, header, now + 301)) throw new Error("a stale timestamp must be rejected");

Reject on mismatch, before touching any state - fail closed.

Event set

VersionEvents
1.0.0settlement.checkpointed · settlement.final · capture.created (credit card) · refund.final · stream.revoked · stream.exhausted · budget.released · budget.halted
1.1.0subscription.period_opened · subscription.renewal_declined · subscription.closed
1.2.0mandate.refused · approval.requested · approval.decided · stream.frozen · stream.thawed · budget.stopped · stream.amended · cap.threshold · velocity.exceeded · payee.new · settlement.failed
1.3.0reservation.expired
1.4.0main_switch.paused · main_switch.resumed
1.5.0payee.destination_updated · payment.recorded · vault.changed
1.6.0the Task Allowance (task.), policies (policy.), recourse (recourse.) and organisations (org.)

The catalogue route lists every type with its fields. budget.halted carries an objective reason code only (revoked, anomaly, sla, budget_closed, exposure, rate, payer_concurrency, cap, ceiling_dead) - never a subjective judgment.

Merchant API subscriptions

Subscriptions made through the merchant API (POST /v1/webhooks, GET /v1/webhooks, DELETE /v1/webhooks/{id}, bearer-authenticated and ownership-scoped) are delivered with x-dynamo-event-id and x-dynamo-signature: sha256=<hex HMAC-SHA256> over the exact request body with your subscription secret.

A subscription receives only the events about its own service node: events that name it, and events about a stream that pays it. Budget, organisation, policy and recourse events are the owner's, and reach owner endpoints only. The target follows the same rules as a signed endpoint (see allowed targets).

This sample is the complete check:

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

function verifyDelivery(secret: string, rawBody: string, signatureHeader: string): boolean {
  const expected = `sha256=${createHmac("sha256", secret).update(rawBody, "utf8").digest("hex")}`;
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader);
  return a.length === b.length && timingSafeEqual(a, b);
}

const secret = "whsec_example_docs_secret";
const body = JSON.stringify({
  id: "evt_0123456789abcdef01234567",
  type: "settlement.final",
  schemaVersion: "1.1.0",
  occurredAt: "1754000000",
  externalRef: "order-42",
  data: {},
});
const signature = `sha256=${createHmac("sha256", secret).update(body, "utf8").digest("hex")}`;

if (!verifyDelivery(secret, body, signature)) throw new Error("valid signature must verify");
if (verifyDelivery(secret, body.replace("final", "FINAL"), signature)) {
  throw new Error("a tampered body must be rejected");
}

The reference consumer

@dynamo/events ships ReferenceConsumer, the executable form of the rules above for merchant API subscriptions: HMAC check, event-id dedupe, monotone cumulative settlements, credit on final only. make demo-webhook-dupes runs two live HTTP consumers: one receives every event once, in order; the other receives the same events plus every event twice more, shuffled. The demo proves both end in byte-identical state, rejects a forged signature without touching state, and checks the credited amount against the session's settled total. Copy the consumer, or copy its rules.