API reference

Webhooks API

Create and manage webhooks from code. Every endpoint here needs an API key with the webhooks:manage scope. How deliveries work is described in the Webhooks guide.

The webhook object

json

{
  "id": "hook_01j8z9a1b2c3d4e5f6g7h8j9k0",
  "object": "webhook",
  "name": "Orders system",
  "url": "https://example.com/kweko/webhooks",
  "events": ["lead.created", "lead.stage_changed", "task.*"],
  "filters": { "pipeline_ids": ["pipeline_01j8z5y1b3c5d7e9f1g3h5j7k9"] },
  "active": true,
  "status": "active",
  "failure_count": 0,
  "last_success_at": "2026-09-27T09:41:13Z",
  "disabled_at": null,
  "disabled_reason": "",
  "created_at": "2026-09-20T10:00:00Z",
  "health": { "delivered": 1204, "failed": 3, "pending": 0 }
}

status is active, failing (recent deliveries fail) or disabled. health counts the last 7 days of deliveries.

Webhooks

GET/v1/webhookswebhooks:manage

All webhooks of the workspace (up to 25), in the list envelope {"object": "list", "data": [...], "has_more": false}.

POST/v1/webhookswebhooks:manage

Field	Description
`name`	Up to 80 characters
`url`	Required. HTTPS, port 443 or 8443, a public address, up to 2048 characters
`events`	Required. 1 to 100 patterns: `lead.created`, `lead.` or ``
`filters`	Optional: `pipeline_ids`, `stage_ids`, `owner_ids`, `channels`, up to 50 values each
`active`	Default `true`

Answers 201 with {"webhook": {…}, "secret": "whsec_…"}. The secret is shown only here and on rotation. Plan and product limits answer limit_reached.

GET/v1/webhooks/eventswebhooks:manage

The event catalog, grouped: {"data": [{"group": "lead", "events": ["lead.created", …]}, …]}. The same list is on the Event catalog page.

GET/v1/webhooks/{id}webhooks:manage

PATCH/v1/webhooks/{id}webhooks:manage

Send only the fields to change. {"active": true} enables a disabled webhook and resets its failure count.

DELETE/v1/webhooks/{id}webhooks:manage

Answers {"id": "hook_…", "deleted": true}. Its delivery log is deleted with it.

Secrets and tests

POST/v1/webhooks/{id}/rotate-secretwebhooks:manage

Answers {"secret": "whsec_…"}. The old secret stops working at once.

POST/v1/webhooks/{id}/pingwebhooks:manage

Sends a ping event now, without retries, and answers {"ok": true, "delivery": {…}} with the result. The ping's data is {"webhook_id": "hook_…"}.

Showing an existing secret again (GET /v1/webhooks/{id}/secret) is only possible in Kweko, not with an API key (permission_denied).

Deliveries

GET/v1/webhooks/{id}/deliverieswebhooks:manage

Parameters: status (success, failed, retrying or pending), limit (1 to 250, default 50), cursor.

json

{
  "id": "dlv_01j8z9b2c3d4e5f6g7h8j9k0m1",
  "object": "webhook_delivery",
  "event_type": "lead.stage_changed",
  "event_id": "evt_482913",
  "status": "success",
  "attempts": 1,
  "status_code": 200,
  "latency_ms": 184,
  "error": "",
  "replay": false,
  "next_attempt_at": null,
  "created_at": "2026-09-27T09:41:12Z",
  "last_attempt_at": "2026-09-27T09:41:13Z"
}

GET/v1/webhooks/{id}/deliveries/{did}webhooks:manage

The delivery with its payload and response_snippet (the first 2 KB of your server's answer).

POST/v1/webhooks/{id}/deliveries/{did}/replaywebhooks:manage

Sends the delivery again as a new delivery with the same event id and Kweko-Replay: true. Answers 202 with the new delivery. A disabled webhook answers webhook_disabled.