Webhooks
Subscribe to events at the org level. Each delivery is signed with the webhook's secret using HMAC-SHA256; verify the signature before trusting the payload.
Generated from src/lib/api-paths/webhooks.ts. The events list comes from CreateWebhookSchema in the runtime — what's documented here is what the API accepts.
get/api/orgs/{slug}/webhooks
List org webhooks
Every webhook configured for the org. Secrets are returned as a preview only.
Auth: Bearer token (API key or OAuth access token).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | yes |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | Webhook list. |
post/api/orgs/{slug}/webhooks
Create a webhook
Register a webhook subscription. The full signing secret is returned exactly once in the response — store it before the response is closed.
Auth: Bearer token (API key or OAuth access token).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
url | string (uri) | yes | |
events | "row.created" | "row.updated" | "row.deleted" | "row.sealed" | "comment.added" | "comment.deleted" | "member.invited" | "member.joined" | "member.removed" | "member.role_changed" | "workspace.created" | "workspace.renamed" | "workspace.columns_updated" | "workspace.visibility_changed" | "workspace.archived" | "doc.created" | "doc.updated" | "doc.heading_added" | "doc.mention_added"[] | no |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | Created. |
400 | Error | URL failed SSRF guard (loopback, private range, cloud metadata). |
patch/api/orgs/{slug}/webhooks/{id}
Toggle webhook active state
Enable or disable a webhook without deleting it. Body: `{ active: boolean }`.
Auth: Bearer token (API key or OAuth access token).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | yes | |
id | string | yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
active | boolean | yes |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | Updated. |
404 | Error | Not found. |
delete/api/orgs/{slug}/webhooks/{id}
Delete a webhook
Removes the subscription. In-flight deliveries are cancelled.
Auth: Bearer token (API key or OAuth access token).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | yes | |
id | string | yes |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | Deleted. |
404 | Error | Not found. |
get/api/orgs/{slug}/webhooks/{id}/deliveries
List recent webhook deliveries
Up to 50 most recent delivery attempts for one webhook, newest first. Use to debug failed integrations or watch retry status.
Auth: Bearer token (API key or OAuth access token).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | yes | |
id | string | yes |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | Delivery list. |
404 | Error | Webhook not found. |
post/api/orgs/{slug}/webhooks/{id}/rotate-secret
Rotate webhook signing secret
Generate a fresh signing secret. Returned exactly once. Subsequent deliveries are signed with the new secret only — update your receiver before the next event lands.
Auth: Bearer token (API key or OAuth access token).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | yes | |
id | string | yes |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | Rotated. |
404 | Error | Not found. |
Events
Pass any subset on events at create time. Adding new event names later requires a schema update in src/lib/schemas.ts + Settings UI; the runtime rejects unknown names.
| Event | When it fires |
|---|---|
row.created | A new row is appended. |
row.updated | Any cell on a row is changed. Includes the diff. |
row.deleted | A row is deleted. |
row.sealed | A row is sealed (writes locked). |
comment.added | A comment is created on any anchor type. |
comment.deleted | A comment is deleted. |
member.invited | An invite is created (workspace or org). |
member.joined | An invitee accepts and a membership row is created. |
member.removed | A member is removed from a workspace, including the cascade from an org-removal. |
member.role_changed | A member's role changes (workspace or org). |
workspace.created | A workspace is created. |
workspace.renamed | A workspace's name (or slug) changes. |
workspace.columns_updated | Columns are added, removed, reordered, or retyped on a table surface. |
workspace.visibility_changed | Workspace visibility flips between private / org / unlisted / public. |
workspace.archived | A workspace is archived (soft-delete). |
doc.created | A workspace is created in doc mode. |
doc.updated | A doc body is replaced or appended-to. |
doc.heading_added | A new heading is written in a doc body. Useful for outline-aware downstream pipelines. |
doc.mention_added | A new @mention or [[cross-ref]] appears in a doc body. |
Signing
Every delivery includes a Dock-Signature header of the form t=<ts>,v1=<hex>. Compute HMAC_SHA256(secret, ts + "." + body); constant-time-compare against v1; reject if ts is more than 5 minutes off your clock.
Related
- Comments API — the source of every
comment.*event listed above. - Agent attribution — every event payload carries the principal that caused it.
- Rate limits — webhook send caps per plan.
- Error codes