Receive webhooks

​

Register an endpoint

import { Checkfu } from "@checkfu/sdk"

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

curl --request POST https://api.checkfu.com/v1/webhook-endpoints \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Checkfu-Version: 2026-08-31" \
  --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"
    ]
  }'

const endpoint = await checkfu.webhooks.create(
  {
    url: "https://example.com/hooks/checkfu",
    event_types: [
      "run.requires_action",
      "action_approval.pending",
      "outcome.evaluation_started",
      "outcome.evaluation_completed",
      "run.completed",
    ],
  },
  { idempotencyKey: "endpoint-production" },
)

• memory_store.created / memory_store.archived / memory_store.deleted — a memory store changed.
• 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.
• automation_firing.failed — an automation firing settled as a failure: its launch never produced a Session (the firing’s status is failed and its error names why), or its step program settled failed or could no longer run. data.resource_id is the firing id; fetch GET /v1/automation-firings/{id} for its automation_id and the reason. Delivered once per firing. A step program that settles denied (a person refused an approval) or rejected (a Check’s negative verdict or an exhausted outcome) reached a decision it was built to make, so it emits no failure. A firing that launched but whose Run later failed is reported by automation_firing.run_failed instead.
• automation_firing.run_failed — an automation firing created its Session, but the Run it launched then failed (for an automation with an outcome, this includes the revision Run that continued its work). data.resource_id is the firing id; its GET /v1/automation-firings/{id} read stays submitted and names the Run in failed_run_id, and GET /v1/runs/{run_id} carries the error. Delivered once per firing, and never for the same firing as automation_firing.failed. A Run someone else started in the automation’s Session, a canceled Run, and an outcome’s verdict emit nothing. Subscribe to both events to hear about every automation failure.
• 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.

​

Verify the signature

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

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)
	})
}

• 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"
  }
}

​

Retries and auto-disable

​

Redeliver a dead letter

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-31" \
  --header "Idempotency-Key: redeliver-$DELIVERY_ID"

​

Test and rotate

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-31" \
  --data '{"expected_version":'"$ENDPOINT_VERSION"'}'

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-31" \
  --header "Idempotency-Key: rotate-$ENDPOINT_ID-$ENDPOINT_VERSION" \
  --data '{"expected_version":'"$ENDPOINT_VERSION"'}'

​

Choosing webhooks or streaming

​

Next steps