Webhooks - signed endpoints and the event catalogue
Signed, at-least-once webhook delivery from a durable outbox. There are two delivery paths:
- Signed webhook endpoints (owner-api 1.6.0 and later, events 1.4.0 and
later): the owner registers endpoints with an event filter; every delivery carries a Dynamo-Signature header. This is the path to use. Status: Live.
- Merchant API subscriptions (events 1.0.0): a service node subscribes
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
| Route | What it does |
|---|---|
POST /owner/v1/webhooks/endpoints | {url, events} → {endpoint, secret}; the whsec_… secret is shown once |
GET /owner/v1/webhooks/endpoints | the 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}/rotate | a 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/catalogue | every event type, its schema version and its data fields; clients pinned at 1.8.0 get the 1.6.0 edition |
Every delivery carries:
Dynamo-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>, computed with
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.
Dynamo-Event-Id: the stable event id you dedupe on.Dynamo-Delivery-Attempt: the attempt number.
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
| Version | Events |
|---|---|
| 1.0.0 | settlement.checkpointed · settlement.final · capture.created (credit card) · refund.final · stream.revoked · stream.exhausted · budget.released · budget.halted |
| 1.1.0 | subscription.period_opened · subscription.renewal_declined · subscription.closed |
| 1.2.0 | mandate.refused · approval.requested · approval.decided · stream.frozen · stream.thawed · budget.stopped · stream.amended · cap.threshold · velocity.exceeded · payee.new · settlement.failed |
| 1.3.0 | reservation.expired |
| 1.4.0 | main_switch.paused · main_switch.resumed |
| 1.5.0 | payee.destination_updated · payment.recorded · vault.changed |
| 1.6.0 | the 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.