Events API
Things that happened in the account (also delivered to webhook endpoints).
Kept for 30 days.
| Operation | Endpoint |
|---|---|
| List events | GET /v1/events |
| Retrieve an event | GET /v1/events/{event} |
The Event object
Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days).
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier of the event (evt_…). |
object | enum | String representing the object's type. Always "event". |
type | string | Event type: 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. |
api_version | string | API version used to render data.object. |
created | integer | When the event happened. Unix timestamp in seconds. |
livemode | boolean | true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox). |
data | object | Event payload. |
data.object | object | The object the event is about (a site, finding, scan, certificate, law_update or notice), as the API returns it. |
data.previous_attributes | object | For *_changed events: the previous values of the changed fields. |
pending_webhooks | integer | Webhook deliveries not yet acknowledged. |
request | object | What caused the event. |
request.id | string | null | API request that caused the event (null for automatic changes). |
request.idempotency_key | string | null | Idempotency-Key of that request. |
List events
GET /v1/events
Events newest first. Poll with ending_before=<newest id you have> to get only new events (an alternative to webhooks).
Scope events:read · Operation listEvents
SDK: checkbox.events.list() (Node) · checkbox.events.list() (Python). MCP / agents: operation listEvents.
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). |
type | query | string | Only this type; a trailing * matches a prefix (finding.*). |
created_gte | query | integer | null | Only events created at or after this unix time. |
created_lte | query | integer | null | Only events created at or before this unix time. |
Returns
Returns a list ({ object: "list", data, has_more, url }) of Event objects.
Errors use the standard envelope with a stable code and, where useful, next_action.
curl -G https://app.checkbox.site/v1/events \
-u "$CHECKBOX_SECRET_KEY:" \
-d limit=3import Checkbox from '@checkbox-site/cli';
const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);
const events = await checkbox.events.list({ limit: 3 });
console.log(events.data);import os
from checkbox import Checkbox
checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])
events = checkbox.events.list(limit=3)
print(events.data){
"object": "list",
"data": [
{
"id": "evt_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
"object": "event",
"type": "finding.created",
"api_version": "2026-10-30",
"created": 1793318400,
"livemode": false,
"data": {
"object": {
"id": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
"object": "finding"
},
"previous_attributes": {
"score": 74
}
},
"pending_webhooks": 0,
"request": {
"id": null,
"idempotency_key": null
}
}
],
"has_more": false,
"url": "/v1/sites"
}Retrieve an event
GET /v1/events/{event}
One event with its payload (data.object) and the number of webhook deliveries still pending.
Scope events:read · Operation retrieveEvent
SDK: checkbox.events.retrieve() (Node) · checkbox.events.retrieve() (Python). MCP / agents: operation retrieveEvent.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
event required | path | string | Unique identifier of the event (evt_…). |
Returns
Returns an Event object.
Errors use the standard envelope with a stable code and, where useful, next_action.
curl https://app.checkbox.site/v1/events/evt_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
-u "$CHECKBOX_SECRET_KEY:"import Checkbox from '@checkbox-site/cli';
const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);
const event = await checkbox.events.retrieve('evt_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(event);import os
from checkbox import Checkbox
checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])
event = checkbox.events.retrieve("evt_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(event){
"id": "evt_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
"object": "event",
"type": "finding.created",
"api_version": "2026-10-30",
"created": 1793318400,
"livemode": false,
"data": {
"object": {
"id": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
"object": "finding"
},
"previous_attributes": {
"score": 74
}
},
"pending_webhooks": 0,
"request": {
"id": null,
"idempotency_key": null
}
}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.