Overview

Register an endpoint and KeyPair posts an event the moment something happens — a deposit clears, a withdrawal lands, reconciliation finds drift — instead of you polling for it.

The envelope

Every delivery has the same shape:

{
	"event": "deposit.confirmed",
	"id": "d5f1c0e2-…",
	"createdAt": "2026-08-26T01:12:44.000Z",
	"data": { "...": "event-specific" }
}

Verify the signature

Signed over the raw request body — re-serialising the parsed JSON changes the bytes and breaks the check:

t=<timestamp>,v1=<hmac>

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

function verify(rawBody: string, header: string, secret: string): boolean {
	const [tPart, vPart] = header.split(",");
	const timestamp = tPart.split("=")[1];
	const expected = createHmac("sha256", secret)
		.update(`${timestamp}.${rawBody}`)
		.digest("hex");
	return timingSafeEqual(Buffer.from(vPart.split("=")[1]), Buffer.from(expected));
}

Verify against the raw bytes your framework received, before any JSON parsing. Most frameworks parse the body before your handler runs by default — you likely need to opt into the raw body for this route specifically.

Deduplicate

Delivery is at-least-once. Key your dedup on x-keypair-delivery (also present as the event’s id), not on the event type plus timestamp — a redelivered event reuses the same id.

Respond fast

Return 2xx as soon as you’ve durably queued the event — do the actual work afterward. Anything else is treated as a failed attempt and retried with backoff.

Get started

Core concepts

Webhooks

The envelope

Verify the signature

Deduplicate

Respond fast

Every event and its payload