Receive webhooks

Verify a Checkfu signature, deduplicate deliveries, and survive retries.

Webhooks tell you something happened without holding a stream open. The delivery is deliberately thin: verify it, deduplicate it, then fetch what you need.

Register an endpoint

CHECKFU_API_KEY and CHECKFU_WORKSPACE_ID come from Get access. The TypeScript tabs below use the TypeScript SDK with this client:

import { Checkfu } from "@checkfu/sdk"

const checkfu = new Checkfu({
  apiKey: process.env.CHECKFU_API_KEY,
})

cURL

curl --request POST https://api.checkfu.com/v1/webhook-endpoints \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Checkfu-Version: 2026-08-27" \
  --header "Idempotency-Key: endpoint-production" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/hooks/checkfu",
    "event_types": [
      "run.requires_action",
      "action_approval.pending",
      "outcome.evaluation_started",
      "outcome.evaluation_completed",
      "run.completed"
    ]
  }'

To subscribe to the whole catalog, omit event_types entirely. Sending null is valid when patching an existing endpoint but is rejected at creation, and an empty array is rejected in both.

Beside the session-log lifecycle, the catalog carries resource-lifecycle events, delivered with a null data.session_id and the mutated resource’s identity in data.resource_id so one get-by-id completes the read:

• memory_store.created / memory_store.archived / memory_store.deleted — a memory store changed, including the platform-created output store a completed dream leaves behind, which no customer call made.
• agent.created / agent.updated / agent.archived — an Agent changed. Every effective update automatically creates the next immutable Version; fetch the Agent to read its current version.
• connection.created / connection.revoked / connection.refresh_failed — a connection was created, entered revoked, or a credential refresh failed and left it needing reauthorization.
• vault_credential.refresh_failed — an attached Vault Credential’s OAuth access token expired and could not be renewed. The expired token is not released to the Session; use data.vault_id and data.resource_id as the nested Vault/Credential lookup pair to inspect its secret-free state before replacing or revalidating it.
• automation.created / automation.paused / automation.resumed / automation.deleted — an automation’s lifecycle changed. Automations have no archive state; deletion is the terminal transition.
• workspace.created / workspace.updated — a non-bootstrap Workspace was created from an existing Workspace context, or a Workspace’s versioned configuration/status changed. Creation is delivered through the request Workspace’s pre-existing custodian; bootstrap creates the first Workspace and has no possible Workspace-scoped subscriber, so it emits no fact. Workspaces have no delete/archive operation; disabling one is an update and its custodian remains addressable.
• sandbox_profile.created / sandbox_profile.updated — a SandboxProfile was created with immutable revision 1, or a later immutable revision advanced its aggregate head. Fetch the SandboxProfile by data.resource_id to read the current template and revision number. SandboxProfiles expose no archive/delete operation.

The response contains the signing secret. Create and rotation require an Idempotency-Key; an exact retry can recover the same response if the first response was lost, but never mints a second secret generation for that operation. Store the secret before using a different key or changing the endpoint version.

Verify the signature

Checkfu-Signature: t=1752686400,v1=<hex hmac-sha256>

The HMAC is computed over ASCII(t) || "." || raw_request_body, keyed by the whole whsec_… secret as UTF-8 bytes.

path=examples/support-desk/server/src/checkfu-webhook.ts

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

const DEFAULT_TOLERANCE_SECONDS = 300
const SHA256_HEX_LENGTH = 64

export interface CheckfuWebhookVerification {
	rawBody: Uint8Array
	signatureHeader: string | null
	secrets: ReadonlyArray<string>
	nowSeconds?: number
	toleranceSeconds?: number
}

const parseSignatureHeader = (
	header: string,
): { readonly timestamp: string; readonly signature: string } | null => {
	const fields = new Map<string, Array<string>>()
	for (const rawField of header.split(",")) {
		const field = rawField.trim()
		const separator = field.indexOf("=")
		if (separator <= 0) return null
		const key = field.slice(0, separator)
		const value = field.slice(separator + 1)
		fields.set(key, [...(fields.get(key) ?? []), value])
	}

	const timestamps = fields.get("t") ?? []
	const signatures = fields.get("v1") ?? []
	if (timestamps.length !== 1 || signatures.length !== 1) return null
	const timestamp = timestamps[0]
	const signature = signatures[0]
	if (timestamp === undefined || !/^\d+$/u.test(timestamp)) return null
	if (signature === undefined || !/^[a-f\d]{64}$/iu.test(signature)) return null
	return { timestamp, signature }
}

/** Verify one Checkfu delivery against the active and, during rotation, previous secret. */
export const verifyCheckfuWebhookSignature = ({
	rawBody,
	signatureHeader,
	secrets,
	nowSeconds = Math.floor(Date.now() / 1000),
	toleranceSeconds = DEFAULT_TOLERANCE_SECONDS,
}: CheckfuWebhookVerification): boolean => {
	if (
		signatureHeader === null ||
		secrets.length === 0 ||
		!Number.isSafeInteger(nowSeconds) ||
		!Number.isSafeInteger(toleranceSeconds) ||
		toleranceSeconds < 0
	) {
		return false
	}
	const parsed = parseSignatureHeader(signatureHeader)
	if (parsed === null) return false

	const timestampSeconds = Number(parsed.timestamp)
	if (
		!Number.isSafeInteger(timestampSeconds) ||
		Math.abs(nowSeconds - timestampSeconds) > toleranceSeconds
	) {
		return false
	}

	const provided = Buffer.from(parsed.signature, "hex")
	if (provided.length * 2 !== SHA256_HEX_LENGTH) return false
	return secrets.some((secret) => {
		const expected = createHmac("sha256", secret)
			.update(parsed.timestamp, "ascii")
			.update(".", "ascii")
			.update(rawBody)
			.digest()
		return timingSafeEqual(provided, expected)
	})
}

Pass the bytes returned by your framework’s raw-body API, the Checkfu-Signature header, and an array containing the current secret. Malformed or duplicate t/v1 fields, invalid hex, and timestamps more than five minutes away all fail closed.

Two details that cause most failures:

• Sign the raw bytes. The body is not normalized before verification. If your framework parses JSON and you re-serialize it to verify, the signature will not match. Capture the raw body.
• The key is the full secret string, including the whsec_ prefix. Do not key on the decoded suffix.

Handle the delivery

{
  "type": "event",
  "id": "evt_0123456789abcdef0123456789abcdef",
  "seq": 12,
  "created_at": "2026-07-16T18:00:03.000Z",
  "data": {
    "type": "run.requires_action",
    "session_id": "sess_0123456789abcdef0123456789abcdef",
    "workspace_id": "wrkspc_0123456789abcdef0123456789abcdef"
  }
}

There is no payload content by design. Deduplicate on id, then fetch the Session or Run for detail. Respond 2xx quickly and do the work asynchronously. The delivery timeout is 10 seconds.

data.session_id is nullable: it is null on test deliveries, which also carry seq: 0. Handle that before dereferencing it, or the first press of the test button crashes your handler.

Retries and auto-disable

Delivery is at-least-once. A failed delivery retries at 30 seconds, 2 minutes, 10 minutes, 1 hour, 4 hours, and 12 hours, for seven attempts in total.

After 20 consecutive terminal failures the endpoint disables itself with a reason of delivery_failures. Re-enable it by patching status back to active, which also resets the failure count. Check GET /v1/webhook-endpoints/{id}/deliveries to see what was failing before you re-enable.

That listing takes order=asc or order=desc, and desc is what you want here: it walks the newest deliveries first, so the failures that disabled the endpoint are on the first page. The cursor does not encode a direction, so send the same order with every page request of a walk, including the ones that carry a page cursor.

Redeliver a dead letter

After fixing the receiver, re-enable or update the endpoint first. Then queue the failed delivery again:

curl --request POST \
  "https://api.checkfu.com/v1/webhook-endpoints/$ENDPOINT_ID/deliveries/$DELIVERY_ID/redeliver" \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Checkfu-Version: 2026-08-27" \
  --header "Idempotency-Key: redeliver-$DELIVERY_ID"

Only a dead-lettered delivery on an active endpoint can be redelivered. The response is a 202 queued receipt. An exact retry with the same idempotency key returns that receipt without queueing twice.

Redelivery preserves the original delivery ID, event ID, sequence, timestamp, and thin body. It adds one delivery attempt; it does not fabricate a second event or reset the attempt count. Because webhook attempts are independent, the redelivered notification can arrive after notifications for newer events. Continue deduplicating on id and do not infer event order from arrival order.

Test and rotate

Read the endpoint’s current version from its create, get, list, or patch response. Testing and rotation require that reviewed version and reject the request if the endpoint changed before the action ran.

curl --request POST \
  "https://api.checkfu.com/v1/webhook-endpoints/$ENDPOINT_ID/test" \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Checkfu-Version: 2026-08-27" \
  --data "{\"expected_version\":$ENDPOINT_VERSION}"

This sends a synthetic delivery with the event type webhook.test and reports whether it arrived and with what status code. That type never appears in a real event log, so it is safe to special-case.

Plan a coordinated cutover, then rotate with a unique idempotency key:

curl --request POST \
  "https://api.checkfu.com/v1/webhook-endpoints/$ENDPOINT_ID/rotate-secret" \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Checkfu-Version: 2026-08-27" \
  --header "Idempotency-Key: rotate-$ENDPOINT_ID-$ENDPOINT_VERSION" \
  --data "{\"expected_version\":$ENDPOINT_VERSION}"

The response returns the new secret exactly once and advances the endpoint version. Checkfu switches subsequent deliveries immediately; the retired secret no longer verifies them. Store the response, deploy the new secret to every receiver promptly, and retry the exact request with the same idempotency key if response delivery is interrupted. Rotation has no overlap window, so schedule it when a brief delivery-retry interval is acceptable.

Deletion uses the same fence: send { "expected_version": <current version> } as the DELETE /v1/webhook-endpoints/{id} body.

Choosing webhooks or streaming

	Webhooks	SSE stream
Best for	Server-to-server, long-running, many Sessions	One Session a user is watching
Delivery	At-least-once with retries	At-least-once with cursor resume
Content	Notification only	Full event envelopes
Excludes	Your own user.* events	Nothing

They are complementary: a dashboard usually streams the Session in front of the user and takes webhooks for everything else.

Next steps

Automations and operations

Inbound ingest uses the identical signature scheme in the other direction.

Resume a stream

The streaming half of the same problem.