Webhook endpoints API

Endpoints that receive signed events.

Verify Checkbox-Signature with the endpoint secret (HMAC-SHA256 of "{t}.{raw body}", 5-minute tolerance). Failed deliveries are retried with backoff for about three days.

Operation	Endpoint
List webhook endpoints	`GET /v1/webhook_endpoints`
Create a webhook endpoint	`POST /v1/webhook_endpoints`
Retrieve a webhook endpoint	`GET /v1/webhook_endpoints/{webhook_endpoint}`
Update a webhook endpoint	`POST /v1/webhook_endpoints/{webhook_endpoint}`
Delete a webhook endpoint	`DELETE /v1/webhook_endpoints/{webhook_endpoint}`
Roll a webhook signing secret	`POST /v1/webhook_endpoints/{webhook_endpoint}/roll_secret`

The WebhookEndpoint object

Where Checkbox sends signed event notifications (Checkbox-Signature: t=…,v1=…).

Field	Type	Description
`id`	string	Unique identifier of the webhook endpoint (we_…).
`object`	enum	String representing the object's type. Always "webhook_endpoint".
`livemode`	boolean	true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).
`url`	string	HTTPS URL Checkbox POSTs events to.
`description`	string \| null	Your description.
`enabled_events`	array of strings	Event types sent to this endpoint ("*" = all).
`status`	enum	Disabled endpoints receive nothing. One of `enabled`, `disabled`.
`api_version`	string	API version events are rendered with.
`metadata`	object	Up to 20 key/value string pairs you can attach to the object.
`secret`	string	Signing secret (whsec_…). Only returned when the endpoint is created or the secret is rolled; store it.
`created`	integer	When the endpoint was created. Unix timestamp in seconds.

List webhook endpoints

GET /v1/webhook_endpoints

Webhook endpoints of this mode, newest first.

Scope webhook_endpoints:read · Operation listWebhookEndpoints

SDK: checkbox.webhookEndpoints.list() (Node) · checkbox.webhook_endpoints.list() (Python). MCP / agents: operation listWebhookEndpoints.

Parameters

Parameter	In	Type	Description
`limit`	query	integer	Number of objects to return, 1-100 (default 10).
`starting_after`	query	string	Cursor: an object id; returns the objects after it (older).
`ending_before`	query	string	Cursor: an object id; returns the objects before it (newer).

Returns

Returns a list ({ object: "list", data, has_more, url }) of WebhookEndpoint objects.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl -G https://app.checkbox.site/v1/webhook_endpoints \
  -u "$CHECKBOX_SECRET_KEY:" \
  -d limit=3

import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const webhookEndpoints = await checkbox.webhookEndpoints.list({ limit: 3 });
console.log(webhookEndpoints.data);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

webhook_endpoints = checkbox.webhook_endpoints.list(limit=3)
print(webhook_endpoints.data)

Response

{
  "object": "list",
  "data": [
    {
      "id": "we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "object": "webhook_endpoint",
      "livemode": false,
      "url": "https://acme.example/webhooks/checkbox",
      "description": "Production listener",
      "enabled_events": [
        "*"
      ],
      "status": "enabled",
      "api_version": "2026-10-30",
      "metadata": {
        "order_ref": "A-1001"
      },
      "secret": "whsec_6Jf…",
      "created": 1793318400
    }
  ],
  "has_more": false,
  "url": "/v1/sites"
}

Create a webhook endpoint

POST /v1/webhook_endpoints

Registers an HTTPS endpoint for the given event types. The response contains the signing secret (only now). Respond 2xx quickly; do slow work asynchronously.

Scope webhook_endpoints:write · Idempotent (send Idempotency-Key) · Operation createWebhookEndpoint

SDK: checkbox.webhookEndpoints.create() (Node) · checkbox.webhook_endpoints.create() (Python). MCP / agents: operation createWebhookEndpoint.

Body

Field	Type	Description
`url` required	string	HTTPS URL.
`enabled_events` required	array of strings	Event types to send, or ["*"] for all: site.score_changed, site.insurable_changed, finding.created, finding.resolved, scan.completed, scan.failed, law.changed, certificate.issued, certificate.lapsed, certificate.revoked, notice.sent, consent.created, test_run.completed, test_run.failed, plan.updated, site.compliant, task.verified.
`description`	string	Description.
`metadata`	object	Up to 20 key/value string pairs you can attach to the object.

Returns

Returns a WebhookEndpoint object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/webhook_endpoints \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://acme.example/webhooks/checkbox",
  "enabled_events": [
    "finding.created",
    "site.insurable_changed"
  ]
}'

import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const webhookEndpoint = await checkbox.webhookEndpoints.create({
  url: 'https://acme.example/webhooks/checkbox',
  enabled_events: ['finding.created', 'site.insurable_changed'],
});
console.log(webhookEndpoint);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

webhook_endpoint = checkbox.webhook_endpoints.create(
    url="https://acme.example/webhooks/checkbox",
    enabled_events=["finding.created", "site.insurable_changed"],
)
print(webhook_endpoint)

Response

{
  "id": "we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "webhook_endpoint",
  "livemode": false,
  "url": "https://acme.example/webhooks/checkbox",
  "description": "Production listener",
  "enabled_events": [
    "*"
  ],
  "status": "enabled",
  "api_version": "2026-10-30",
  "metadata": {
    "order_ref": "A-1001"
  },
  "secret": "whsec_6Jf…",
  "created": 1793318400
}

Retrieve a webhook endpoint

GET /v1/webhook_endpoints/{webhook_endpoint}

One webhook endpoint (without its secret).

Scope webhook_endpoints:read · Operation retrieveWebhookEndpoint

SDK: checkbox.webhookEndpoints.retrieve() (Node) · checkbox.webhook_endpoints.retrieve() (Python). MCP / agents: operation retrieveWebhookEndpoint.

Parameters

Parameter	In	Type	Description
`webhook_endpoint` required	path	string	Unique identifier of the webhook endpoint (we_…).

Returns

Returns a WebhookEndpoint object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/webhook_endpoints/we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
  -u "$CHECKBOX_SECRET_KEY:"

import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const webhookEndpoint = await checkbox.webhookEndpoints.retrieve('we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(webhookEndpoint);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

webhook_endpoint = checkbox.webhook_endpoints.retrieve("we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(webhook_endpoint)

Response

{
  "id": "we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "webhook_endpoint",
  "livemode": false,
  "url": "https://acme.example/webhooks/checkbox",
  "description": "Production listener",
  "enabled_events": [
    "*"
  ],
  "status": "enabled",
  "api_version": "2026-10-30",
  "metadata": {
    "order_ref": "A-1001"
  },
  "secret": "whsec_6Jf…",
  "created": 1793318400
}

Update a webhook endpoint

POST /v1/webhook_endpoints/{webhook_endpoint}

Changes the URL, event types, description, metadata, or disables / re-enables the endpoint.

Scope webhook_endpoints:write · Idempotent (send Idempotency-Key) · Operation updateWebhookEndpoint

SDK: checkbox.webhookEndpoints.update() (Node) · checkbox.webhook_endpoints.update() (Python). MCP / agents: operation updateWebhookEndpoint.

Parameters

Parameter	In	Type	Description
`webhook_endpoint` required	path	string	Unique identifier of the webhook endpoint (we_…).

Body

Field	Type	Description
`url`	string	HTTPS URL.
`enabled_events`	array of strings	Event types to send, or ["*"] for all: site.score_changed, site.insurable_changed, finding.created, finding.resolved, scan.completed, scan.failed, law.changed, certificate.issued, certificate.lapsed, certificate.revoked, notice.sent, consent.created, test_run.completed, test_run.failed, plan.updated, site.compliant, task.verified.
`description`	string \| null	Description (null clears it).
`disabled`	boolean	true disables the endpoint, false enables it.
`metadata`	object	Up to 20 key/value string pairs you can attach to the object.

Returns

Returns a WebhookEndpoint object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/webhook_endpoints/we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled_events": [
    "finding.created",
    "site.insurable_changed"
  ]
}'

import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const webhookEndpoint = await checkbox.webhookEndpoints.update('we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b', {
  enabled_events: ['finding.created', 'site.insurable_changed'],
});
console.log(webhookEndpoint);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

webhook_endpoint = checkbox.webhook_endpoints.update("we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", enabled_events=["finding.created", "site.insurable_changed"])
print(webhook_endpoint)

Response

{
  "id": "we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "webhook_endpoint",
  "livemode": false,
  "url": "https://acme.example/webhooks/checkbox",
  "description": "Production listener",
  "enabled_events": [
    "*"
  ],
  "status": "enabled",
  "api_version": "2026-10-30",
  "metadata": {
    "order_ref": "A-1001"
  },
  "secret": "whsec_6Jf…",
  "created": 1793318400
}

Delete a webhook endpoint

DELETE /v1/webhook_endpoints/{webhook_endpoint}

Deletes the endpoint; pending deliveries to it are dropped.

Scope webhook_endpoints:write · Operation deleteWebhookEndpoint

SDK: checkbox.webhookEndpoints.del() (Node) · checkbox.webhook_endpoints.delete() (Python). MCP / agents: operation deleteWebhookEndpoint.

Parameters

Parameter	In	Type	Description
`webhook_endpoint` required	path	string	Unique identifier of the webhook endpoint (we_…).

Returns

Returns a DeletedWebhookEndpoint object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/webhook_endpoints/we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
  -u "$CHECKBOX_SECRET_KEY:" \
  -X DELETE

import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const webhookEndpoint = await checkbox.webhookEndpoints.del('we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(webhookEndpoint);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

webhook_endpoint = checkbox.webhook_endpoints.delete("we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(webhook_endpoint)

Response

{
  "id": "we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "webhook_endpoint",
  "deleted": true
}

Roll a webhook signing secret

POST /v1/webhook_endpoints/{webhook_endpoint}/roll_secret

Replaces the signing secret immediately and returns the new one (only now).

Scope webhook_endpoints:write · Idempotent (send Idempotency-Key) · Operation rollWebhookEndpointSecret

SDK: checkbox.webhookEndpoints.rollSecret() (Node) · checkbox.webhook_endpoints.roll_secret() (Python). MCP / agents: operation rollWebhookEndpointSecret.

Parameters

Parameter	In	Type	Description
`webhook_endpoint` required	path	string	Unique identifier of the webhook endpoint (we_…).

Returns

Returns a WebhookEndpoint object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/webhook_endpoints/we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/roll_secret \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{}'

import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const webhookEndpoint = await checkbox.webhookEndpoints.rollSecret('we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(webhookEndpoint);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

webhook_endpoint = checkbox.webhook_endpoints.roll_secret("we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(webhook_endpoint)

Response

{
  "id": "we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "webhook_endpoint",
  "livemode": false,
  "url": "https://acme.example/webhooks/checkbox",
  "description": "Production listener",
  "enabled_events": [
    "*"
  ],
  "status": "enabled",
  "api_version": "2026-10-30",
  "metadata": {
    "order_ref": "A-1001"
  },
  "secret": "whsec_6Jf…",
  "created": 1793318400
}

Checkbox is compliance software, not a law firm; nothing in these docs is legal advice (details). For AI agents: every page is available as Markdown at the same URL plus .md; the index is /llms.txt.

Webhook endpoints API

#The WebhookEndpoint object

#List webhook endpoints

#Parameters

#Returns

#Create a webhook endpoint

#Body

#Returns

#Retrieve a webhook endpoint

#Parameters

#Returns

#Update a webhook endpoint

#Parameters

#Body

#Returns

#Delete a webhook endpoint

#Parameters

#Returns

#Roll a webhook signing secret

#Parameters

#Returns

The WebhookEndpoint object

List webhook endpoints

Parameters

Returns

Create a webhook endpoint

Body

Returns

Retrieve a webhook endpoint

Parameters

Returns

Update a webhook endpoint

Parameters

Body

Returns

Delete a webhook endpoint

Parameters

Returns

Roll a webhook signing secret

Parameters

Returns