Webhooks

Webhooks push every domain event in an Environment to an HTTPS endpoint you control. Each delivery is signed with an endpoint-specific secret, retried on a fixed schedule, and inspectable in the Console under Developers → Webhooks.

Set up an endpoint

Endpoints belong to one Environment: a Test endpoint receives Test events only, and a Live endpoint receives Live events only. Create one in the Console (Developers → Webhooks → Create endpoint) or through the API:

curl -X POST https://your-kordless-instance.com/v1/webhook-endpoints \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "…",
    "environmentId": "…",
    "url": "https://receiver.example.com/kordless",
    "description": "billing reconciler",
    "eventTypes": ["quote_intent.succeeded", "quote_intent.failed"]
  }'

url must be HTTPS and cannot carry credentials or fragments.
eventTypes is a filter list; omit it (or send []) to subscribe to every event type.
The response returns the endpoint plus its signing secret (whsec_…), shown exactly once. Store it immediately; afterwards only a display prefix and the last four characters are retrievable.

The signing secret is the only proof that a delivery came from Kordless. If you lose it, rotate it (POST /v1/webhook-endpoints/{id}/secret-rotation) — it cannot be recovered.

The delivery envelope

Every delivery is a POST with a JSON envelope:

{
  "id": "evt_9c1e…",
  "version": 1,
  "type": "quote_intent.succeeded",
  "created": "2026-08-03T14:02:11.000Z",
  "workspaceId": "…",
  "projectId": "…",
  "environmentId": "…",
  "businessId": "…",
  "data": { "…": "the event payload" }
}

businessId is present on Business-scoped events. version is the envelope schema version (currently 1). Event types:

Type	Fired when
`business.created`	A Business is created.
`business.onboarding_completed`	A Business completes hosted onboarding.
`business_membership.created`	A member joins a Business.
`book_version.published`	A Book Version is published to an Environment.
`book_publication.rolled_back`	An Environment pointer rolls back to a previous Version.
`quote_intent.requires_input`	A Quote completes with structured missing inputs.
`quote_intent.succeeded`	A Quote completes with a priced Receipt.
`quote_intent.failed`	A Quote completes with a terminal unpriced Receipt.
`webhook.test`	A test event you triggered for this endpoint.

Delivery headers

Header	Value
`Kordless-Signature`	`t=<unix seconds>,v1=<hex HMAC-SHA256>` — see verification below.
`Kordless-Event-Id`	The event id; same value as envelope `id`. Use it to deduplicate.
`Kordless-Event-Type`	The event type, for routing before parsing.
`Kordless-Delivery-Id`	Unique per delivery attempt chain, including replays.

Verify the signature

The v1 value is the hex HMAC-SHA256 of the string "<t>.<raw request body>", keyed with the endpoint’s signing secret. Verification has three parts: recompute the digest over the raw, unparsed body, compare it timing-safely against every v1 value in the header, and reject timestamps older than your tolerance (300 seconds recommended).

Always verify against the raw body exactly as received. Parsing the JSON and re-serializing it — even with the same keys — can change whitespace or ordering and will invalidate the signature.

With the SDK:

import { verifyWebhookSignature, WebhookSignatureError } from "@kordless/sdk";

export async function POST(request: Request) {
  try {
    const event = verifyWebhookSignature({
      payload: await request.text(), // raw body — do not JSON.parse first
      signatureHeader: request.headers.get("kordless-signature") ?? "",
      secret: process.env.KORDLESS_WEBHOOK_SECRET!,
      // toleranceSeconds: 300 is the default
    });
    // event is the parsed envelope, verified
    return new Response("ok");
  } catch (error) {
    if (error instanceof WebhookSignatureError) {
      return new Response("invalid signature", { status: 400 });
    }
    throw error;
  }
}

With raw node:crypto (no SDK):

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

function verify(rawBody: string, header: string, secret: string, toleranceSeconds = 300) {
  const parts = new Map(header.split(",").map((p) => p.split("=") as [string, string]));
  const timestamp = Number(parts.get("t"));
  const signatures = header.split(",").filter((p) => p.startsWith("v1=")).map((p) => p.slice(3));
  if (!Number.isFinite(timestamp) || signatures.length === 0) return false;
  if (Math.floor(Date.now() / 1000) - timestamp > toleranceSeconds) return false;

  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`, "utf8").digest();
  return signatures.some((sig) => {
    const candidate = Buffer.from(sig, "hex");
    return candidate.length === expected.length && timingSafeEqual(candidate, expected);
  });
}

The header may carry multiple v1 values during a secret-rotation window; accept the delivery if any of them match, exactly as the snippets above do.

Retries, exhaustion, and replay

Return any 2xx to acknowledge a delivery. Anything else — non-2xx, timeout (deliveries give up after 10 seconds), or a connection failure — schedules a retry:

Attempt	Delay after previous failure
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6 (final)	8 hours

After the fifth failure the delivery is marked exhausted and no further automatic attempts are made. You can then fix your receiver and replay: POST /v1/webhook-deliveries/{deliveryId}/replay (or the replay action in the Console) creates a new pending delivery with the same payload, linked to the original. The original delivery and its attempt history are never mutated.

Test events

POST /v1/webhook-endpoints/{id}/test-events (or Send test event in the Console) queues a webhook.test delivery for one endpoint. It is signed and delivered exactly like a real event, so it exercises your verification code end to end without touching pricing data.

Deduplicate on the event id

Delivery is at-least-once. Retries after a receiver-side commit (for example, your server stored the event but the response timed out) and manual replays can both deliver the same event more than once. Key your idempotency on the event id (Kordless-Event-Id, also envelope id) and skip events you have already processed.

Receiver expectations

Timeout. Respond within 10 seconds; do slow work asynchronously after acknowledging.
Source. Deliveries originate from the Kordless instance’s outbound IP range and are authenticated by signature — treat the signature, not the source IP, as the authentication mechanism.
Ordering. Events for one Environment are delivered in outbox order under normal operation, but retries can reorder individual events; order by created if your consumer requires it.
Secrets. Signing secrets are shown once at creation and rotation. The platform stores them reversibly because it must sign with them — unlike API keys, which are stored as one-way SHA-256 digests. Rotate with POST /v1/webhook-endpoints/{id}/secret-rotation; pending deliveries then sign with the new secret.

Next steps

Request logs — trace a request to its Quote, Book Version, and webhook deliveries.
Errors — the error envelope returned by the endpoint-management routes.
Browse the full API reference for endpoint schemas.

Start here

Core concepts

Distribution

Operations

Set up an endpoint

The delivery envelope

Delivery headers

Verify the signature

Retries, exhaustion, and replay

Test events

Deduplicate on the event id

Receiver expectations

Next steps

​Set up an endpoint

​The delivery envelope

​Delivery headers

​Verify the signature

​Retries, exhaustion, and replay

​Test events

​Deduplicate on the event id

​Receiver expectations

​Next steps

Set up an endpoint

The delivery envelope

Delivery headers

Verify the signature

Retries, exhaustion, and replay

Test events

Deduplicate on the event id

Receiver expectations

Next steps