Webhooks
Webhooks deliver HTTP POST notifications to your endpoint when events occur.
Destinations must use HTTPS and resolve only to public IPv4 or IPv6 addresses.
Private, loopback, link-local and metadata addresses are refused at creation
(400 Bad Request) and checked again at connection time. URLs containing
credentials or fragments are refused. Redirects are not followed, and at most
64 KiB of each response body is read.
Supported events
Section titled “Supported events”Single-item events
Section titled “Single-item events”| Event | Triggered when |
|---|---|
lead.created |
A new lead is created (HTTP 201 on POST /leads) |
lead.updated |
A lead is updated, including dedup merges (POST /leads with duplicate: true) |
lead.deleted |
A lead is deleted |
lead.scored |
A lead score is recalculated |
note.created |
A note is added to a lead |
note.updated |
A note is edited |
note.deleted |
A note is deleted |
A merge never fires
lead.created. Subscribe tolead.updatedif you need to react to dedup write-backs.
Batch events
Section titled “Batch events”Batch operations fire one grouped event instead of N individual events.
| Event | Triggered when | Payload shape |
|---|---|---|
leads.created |
New inserts from POST /leads/batch |
{ ids: [...], count: N } |
leads.updated |
Merges from POST /leads/batch, or PUT /leads/batch |
{ ids: [...], count: N } |
leads.deleted |
DELETE /leads/batch succeeds (for deleted ids) |
{ ids: [...], count: N } |
leads.scored |
POST /leads/score/batch runs |
{ leads: [{id, score}], count: N } |
A single POST /leads/batch can emit both leads.created and leads.updated when the batch mixes inserts and merges.
Lead-flow alert events
Section titled “Lead-flow alert events”Klozeo checks every 15 minutes whether leads still arrive through each API key that has an alert set (PUT /api-keys/{id}/alert). A lead is received when it is created or merged through the key. Silence counts only on the key’s active days, in the workspace’s time zone, and a key that has never received a lead never alerts.
| Event | Triggered when |
|---|---|
source.silent |
No lead received through the key for longer than its maximum gap, counted on its active days |
source.recovered |
A lead is received again through a key that had a source.silent |
These events are never sent through "*". A webhook receives them only if events names them, for example ["source.silent", "source.recovered"]. Klozeo sends one source.silent per silence, then one source.recovered. Turning the alert off or revoking the key ends the silence without an event.
While a key is snoozed, nothing is sent. If leads still do not arrive when the snooze ends, one source.silent follows, with the same incident_id when it repeats an earlier one. If leads arrive again during the snooze, source.recovered is sent only when a source.silent was sent for that silence.
The payload names the key and the workspace, never a lead:
{ "event": "source.silent", "payload": { "incident_id": "6f1c…", "api_key": { "id": "key_…", "name": "Make: website form" }, "workspace": { "id": "…", "name": "Acme" }, "silent_since": "2026-11-16T08:12:00Z", "opened_at": "2026-11-16T14:15:00Z", "max_gap_hours": 6 }, "time": 1794838500}source.recovered also carries recovered_at, the time of the first lead after the silence. Discord and Slack destinations get a short message with the key, the workspace and the times. To set an alert and route these events to Slack, n8n or Make, see Get alerted when leads stop arriving.
List Webhooks
Section titled “List Webhooks”GET /webhooksCreate Webhook
Section titled “Create Webhook”POST /webhooks{ "url": "https://your-server.com/hooks/klozeo", "events": ["lead.created", "lead.updated"], "secret": "optional-signing-secret"}Response 201 Created: Full webhook object.
If a secret is provided, each request is signed: see Verifying signatures. The secret is never returned.
Update Webhook
Section titled “Update Webhook”PATCH /webhooks/{id}{ "url": "https://your-server.com/hooks/klozeo-v2", "events": ["lead.created"], "active": false}Send only the fields to change; the others keep their value. A new secret
rotates the signing secret. A new url is
checked like a new webhook. Deliveries still queued go to the new URL.
Response 200 OK: Full webhook object.
Pause and resume
Section titled “Pause and resume”"active": false pauses the webhook. Nothing is sent while it is paused:
deliveries still queued, and every event raised while paused, are recorded in
the delivery history as dead with reason paused. "active": true resumes
it; only events raised after resuming are delivered. Paused events are not
replayed automatically: redeliver the ones you need
within 72 hours.
Delete Webhook
Section titled “Delete Webhook”DELETE /webhooks/{id}Response 200 OK: Success message.
Payload format
Section titled “Payload format”All timestamps are Unix seconds.
{ "event": "lead.created", "time": 1703520000, "payload": { "id": "cl_...", "name": "Acme", "source": "website", "created_at": 1703520000, "updated_at": 1703520000, "last_interaction_at": 1703520000, "do_not_contact": false }}The payload object depends on the event. lead.created carries the creation request fields plus the generated lead id (the same cl_<uuid> returned by POST /leads), its created_at, updated_at and last_interaction_at, the stored status (new when the request had none) and the stored do-not-contact state: do_not_contact always (false included), plus do_not_contact_at and do_not_contact_origin when the lead is opposed, and locked_fields ([] for a new lead), without assignee; update events carry the stored lead (including locked_fields, and "locked": true on each locked custom attribute it carries) without do_not_contact_by or assignee; locking or unlocking a field fires lead.updated, locking or unlocking a custom attribute fires no event, note events carry the note without author, and deletion events carry its ID. Batch events carry { ids, count }, except scoring batches which carry { leads: [{ id, score }], count }.
Verifying signatures
Section titled “Verifying signatures”Set a secret on every webhook that calls your own server. The dashboard
generates one for each new webhook. Each request then carries:
| Header | Content |
|---|---|
Klozeo-Signature |
t=<unix seconds>,v1=<signature>: HMAC-SHA256, hex-encoded, of <t>.<raw body> |
X-Webhook-Signature |
HMAC-SHA256, hex-encoded, of the raw body (legacy) |
Verify Klozeo-Signature: it includes the time of the attempt, so a captured
request cannot be replayed later. Reject a request whose t= timestamp is more than 5
minutes away from your clock. The timestamp changes on every retry; the body does not.
The SDKs include a helper. Pass the raw body, before any JSON parsing:
import { verifyWebhookSignature } from "@klozeo/sdk";
const ok = await verifyWebhookSignature(rawBody, req.headers["klozeo-signature"], secret);if (!ok) return res.status(401).end();from klozeo import verify_webhook_signature
if not verify_webhook_signature(request.get_data(), request.headers.get("Klozeo-Signature"), secret): return "", 401Both accept a tolerance in seconds (toleranceSeconds / tolerance=, default
300). Without the SDK:
import hmac, hashlib, time
def verify(body: bytes, header: str, secret: str, tolerance: int = 300) -> bool: parts = [p.split("=", 1) for p in header.split(",") if "=" in p] t = next((v for k, v in parts if k == "t"), "") if not t.isdigit() or abs(time.time() - int(t)) > tolerance: return False expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest() return any(k == "v1" and hmac.compare_digest(v, expected) for k, v in parts)X-Webhook-Signature is unchanged, for receivers that already verify it. It
has no timestamp and only carries the current secret; prefer
Klozeo-Signature. Its removal, if any, will be announced in the changelog
well in advance.
Rotating the secret
Section titled “Rotating the secret”Send a new secret with PATCH /webhooks/{id}. Klozeo signs with the new
secret at once. For the next 24 hours, Klozeo-Signature carries a second
v1= entry computed with the previous secret, so your endpoint keeps accepting
requests while you deploy the new secret; accept a request when any v1= entry
matches. X-Webhook-Signature switches to the new secret immediately.
Delivery & reliability
Section titled “Delivery & reliability”Delivery is asynchronous. A write and the deliveries of its event commit together in PostgreSQL, or not at all: a committed write always has its event queued, and a write that is rolled back queues none. If the event cannot be queued, the write is rolled back and fails with HTTP 500; retry it.
A missing response does not mean the write was rolled back. The write may have committed before a crash, a timeout or a lost connection, and closing the connection does not stop a write in progress. Retrying after such an unknown outcome may apply the write again and queue a second event, with new event and delivery IDs.
The API worker resumes queued deliveries after a restart. Delivery is at least once.
Return 2xx within 10 seconds. Network failures, HTTP 408/429 and 5xx retry
up to 10 attempts within 24 hours. The nine retry delays are 1m, 5m, 15m, 30m,
1h, 2h, 4h, 6h and 10h, each shortened randomly by 0–2%. Attempt ten is around
23h22m–23h51m after the first, excluding processing time; the 24-hour expiry
always applies. Other 3xx/4xx and unsafe destinations go to dead-letter.
Failures never automatically disable subscriptions. When a delivery is
dead-lettered after 10 or more failed attempts in a row on that webhook, Klozeo
emails the workspace’s owner, and its admins when the workspace is on a paid
plan, at most once per webhook every 24 hours. Delivery order is not
guaranteed: retried events can arrive after newer events.
Deduplicate using X-Webhook-Delivery-ID. X-Webhook-Event-ID identifies the
same event across subscriptions. Both headers and the exact signed body remain
stable across retries. HTTPS destinations are checked against private networks
on every attempt; redirects are refused.
Delivery history
Section titled “Delivery history”The owner or an admin can view Dashboard → Webhooks → Recent deliveries, or call
GET /webhooks/deliveries for the latest 100 receipts. Each receipt includes
id, event_id, webhook_id, event, state (pending, delivered, dead),
reason (paused for an event the webhook skipped while paused), attempts, status, created_at and next_at. Status 0 means no HTTP
response; next_at is meaningful only while pending (retry or lease expiry).
redelivery_of is empty (null), or for a redelivery the ID of the original delivery.
Receipts exclude payloads, URLs, secrets and remote response bodies. A payload
is cleared once delivered. A dead delivery keeps its payload 72 hours after
its event, for redelivery, then it is cleared; a redelivery of that event
still queued then stops, as dead with reason window_exhausted. Receipt metadata remains until
the webhook or account is deleted; deletion also removes stored payloads.
Redeliver a delivery
Section titled “Redeliver a delivery”POST /webhooks/deliveries/{id}/redeliverQueues a dead delivery again, for example after you fixed your endpoint or
resumed a paused webhook. The redelivery is a new delivery: a new
X-Webhook-Delivery-ID, the same X-Webhook-Event-ID and the same body, sent
to the webhook’s current URL and signed with its current secret. It then
follows the normal retry schedule. Deduplicate on X-Webhook-Event-ID if you
may already have processed the event.
Response 202 Accepted: the new delivery receipt, with redelivery_of
set to the original delivery.
| Status | When |
|---|---|
404 |
No delivery with this ID in your account |
409 |
The delivery is not dead, the webhook is paused, a redelivery of this event is already queued, or its payload is gone (the event was delivered, or is more than 72 hours old) |
429 |
100 redeliveries in the last hour for your account, including those of deleted webhooks; wait Retry-After seconds |
Redelivering a redelivery repeats its original event. One redelivery per event can be queued at a time. Once a redelivery is delivered, the event’s payload is cleared and the event can no longer be redelivered.
Endpoint reference
Section titled “Endpoint reference”Paths include the /api/v1 prefix. Schema fields marked required must be present; other fields may be omitted. Nullable values are shown explicitly.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/webhooks |
List webhooks |
| POST | /api/v1/webhooks |
Create webhook |
| GET | /api/v1/webhooks/deliveries |
List webhook deliveries |
| POST | /api/v1/webhooks/deliveries/{id}/redeliver |
Redeliver a webhook delivery |
| PATCH | /api/v1/webhooks/{id} |
Update webhook |
| DELETE | /api/v1/webhooks/{id} |
Delete webhook |
GET /api/v1/webhooks
Section titled “GET /api/v1/webhooks”List webhooks
Accepted authentication: ApiKey or BearerKey.
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: Webhooks |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 400 | Request rejected. | application/json: Error400 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 401 | Invalid or missing credentials. | application/json: Error401 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 403 | Permission denied. Create lead also returns leads_limit_reached when the storage quota is reached. lead_access_required: an admin without lead access from the workspace owner, on the dashboard or an assistant connection. That admin can still manage API keys, webhooks, scoring rules and the lock policy. API keys never get it. workspace_read_only: the workspace is read-only because its owner owns another Free workspace ranked before it (their first workspace, otherwise the oldest), and only one Free workspace per owner stays editable. Editing resumes when this workspace moves to Pro or Scale, or when its owner no longer owns any Free workspace ranked before it. Every change to leads, scoring rules, the status list and the lock policy is refused, from an API key, the dashboard or an assistant connection. Reading, export, members, API keys, webhooks and assistant connections still work. | application/json: Error403 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.; WWW-Authenticate: {"type":"string"} Present for MCP insufficient_scope. |
| 413 | Body exceeds 1 MiB (10 MiB for /leads/batch). | application/json: Error413 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 429 | Rate limit exceeded. Retry-After is always present. Quota exhaustion (computed or cached) includes all four X-RateLimit-* headers. The earlier per-key admission-work refusal can omit those quota headers. | application/json: Error429 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.; Retry-After: {"type":"integer"} Seconds until retry. Early admission refusals may omit the quota headers. |
| 500 | Internal error. | application/json: Error500 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 503 | Authentication unavailable. | application/json: Error503 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
POST /api/v1/webhooks
Section titled “POST /api/v1/webhooks”If a webhook with the same URL, the same events (in any order) and the same secret already exists, Klozeo returns it with status 200, whether it is paused or active, instead of creating another subscription with those settings. A request with a different secret creates a new webhook.
Accepted authentication: ApiKey or BearerKey.
| Request content type | Required | Schema |
|---|---|---|
application/json |
yes | CreateWebhookRequest |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: WebhookResponse |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 201 | Success | application/json: WebhookResponse |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 400 | Request rejected. | application/json: Error400 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 401 | Invalid or missing credentials. | application/json: Error401 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 403 | Permission denied. Create lead also returns leads_limit_reached when the storage quota is reached. lead_access_required: an admin without lead access from the workspace owner, on the dashboard or an assistant connection. That admin can still manage API keys, webhooks, scoring rules and the lock policy. API keys never get it. workspace_read_only: the workspace is read-only because its owner owns another Free workspace ranked before it (their first workspace, otherwise the oldest), and only one Free workspace per owner stays editable. Editing resumes when this workspace moves to Pro or Scale, or when its owner no longer owns any Free workspace ranked before it. Every change to leads, scoring rules, the status list and the lock policy is refused, from an API key, the dashboard or an assistant connection. Reading, export, members, API keys, webhooks and assistant connections still work. | application/json: Error403 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.; WWW-Authenticate: {"type":"string"} Present for MCP insufficient_scope. |
| 413 | Body exceeds 1 MiB (10 MiB for /leads/batch). | application/json: Error413 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 429 | Rate limit exceeded. Retry-After is always present. Quota exhaustion (computed or cached) includes all four X-RateLimit-* headers. The earlier per-key admission-work refusal can omit those quota headers. | application/json: Error429 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.; Retry-After: {"type":"integer"} Seconds until retry. Early admission refusals may omit the quota headers. |
| 500 | Internal error. | application/json: Error500 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 503 | Authentication unavailable. | application/json: Error503 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
GET /api/v1/webhooks/deliveries
Section titled “GET /api/v1/webhooks/deliveries”List webhook deliveries
Accepted authentication: ApiKey or BearerKey.
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: Deliveries |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 400 | Request rejected. | application/json: Error400 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 401 | Invalid or missing credentials. | application/json: Error401 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 403 | Permission denied. Create lead also returns leads_limit_reached when the storage quota is reached. lead_access_required: an admin without lead access from the workspace owner, on the dashboard or an assistant connection. That admin can still manage API keys, webhooks, scoring rules and the lock policy. API keys never get it. workspace_read_only: the workspace is read-only because its owner owns another Free workspace ranked before it (their first workspace, otherwise the oldest), and only one Free workspace per owner stays editable. Editing resumes when this workspace moves to Pro or Scale, or when its owner no longer owns any Free workspace ranked before it. Every change to leads, scoring rules, the status list and the lock policy is refused, from an API key, the dashboard or an assistant connection. Reading, export, members, API keys, webhooks and assistant connections still work. | application/json: Error403 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.; WWW-Authenticate: {"type":"string"} Present for MCP insufficient_scope. |
| 413 | Body exceeds 1 MiB (10 MiB for /leads/batch). | application/json: Error413 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 429 | Rate limit exceeded. Retry-After is always present. Quota exhaustion (computed or cached) includes all four X-RateLimit-* headers. The earlier per-key admission-work refusal can omit those quota headers. | application/json: Error429 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.; Retry-After: {"type":"integer"} Seconds until retry. Early admission refusals may omit the quota headers. |
| 500 | Internal error. | application/json: Error500 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 503 | Authentication unavailable. | application/json: Error503 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
POST /api/v1/webhooks/deliveries/{id}/redeliver
Section titled “POST /api/v1/webhooks/deliveries/{id}/redeliver”Queues a dead delivery again as a new delivery with the same event ID and body, to the webhook’s current URL. Possible within 72 hours of the event and while the webhook is active; at most 100 redeliveries per account per rolling hour (429 with Retry-After).
Accepted authentication: ApiKey or BearerKey.
| Parameter | In | Required | Schema | Description |
|---|---|---|---|---|
id |
path | yes | {"type":"string"} |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 202 | Accepted | application/json: WebhookDelivery |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 400 | Request rejected. | application/json: Error400 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 401 | Invalid or missing credentials. | application/json: Error401 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 403 | Permission denied. Create lead also returns leads_limit_reached when the storage quota is reached. lead_access_required: an admin without lead access from the workspace owner, on the dashboard or an assistant connection. That admin can still manage API keys, webhooks, scoring rules and the lock policy. API keys never get it. workspace_read_only: the workspace is read-only because its owner owns another Free workspace ranked before it (their first workspace, otherwise the oldest), and only one Free workspace per owner stays editable. Editing resumes when this workspace moves to Pro or Scale, or when its owner no longer owns any Free workspace ranked before it. Every change to leads, scoring rules, the status list and the lock policy is refused, from an API key, the dashboard or an assistant connection. Reading, export, members, API keys, webhooks and assistant connections still work. | application/json: Error403 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.; WWW-Authenticate: {"type":"string"} Present for MCP insufficient_scope. |
| 404 | Request rejected. | application/json: Error404 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 409 | Request rejected. | application/json: Error409 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 413 | Body exceeds 1 MiB (10 MiB for /leads/batch). | application/json: Error413 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 429 | Rate limit exceeded. Retry-After is always present. Quota exhaustion (computed or cached) includes all four X-RateLimit-* headers. The earlier per-key admission-work refusal can omit those quota headers. | application/json: Error429 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.; Retry-After: {"type":"integer"} Seconds until retry. Early admission refusals may omit the quota headers. |
| 500 | Internal error. | application/json: Error500 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 503 | Authentication unavailable. | application/json: Error503 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
PATCH /api/v1/webhooks/{id}
Section titled “PATCH /api/v1/webhooks/{id}”Changes the given fields; absent fields keep their value. active=false pauses the webhook: queued deliveries and events raised while paused are recorded as dead with reason paused. active=true resumes delivery of new events.
Accepted authentication: ApiKey or BearerKey.
| Parameter | In | Required | Schema | Description |
|---|---|---|---|---|
id |
path | yes | {"type":"string"} |
| Request content type | Required | Schema |
|---|---|---|
application/json |
yes | UpdateWebhookRequest |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: WebhookResponse |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 400 | Request rejected. | application/json: Error400 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 401 | Invalid or missing credentials. | application/json: Error401 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 403 | Permission denied. Create lead also returns leads_limit_reached when the storage quota is reached. lead_access_required: an admin without lead access from the workspace owner, on the dashboard or an assistant connection. That admin can still manage API keys, webhooks, scoring rules and the lock policy. API keys never get it. workspace_read_only: the workspace is read-only because its owner owns another Free workspace ranked before it (their first workspace, otherwise the oldest), and only one Free workspace per owner stays editable. Editing resumes when this workspace moves to Pro or Scale, or when its owner no longer owns any Free workspace ranked before it. Every change to leads, scoring rules, the status list and the lock policy is refused, from an API key, the dashboard or an assistant connection. Reading, export, members, API keys, webhooks and assistant connections still work. | application/json: Error403 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.; WWW-Authenticate: {"type":"string"} Present for MCP insufficient_scope. |
| 404 | Request rejected. | application/json: Error404 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 413 | Body exceeds 1 MiB (10 MiB for /leads/batch). | application/json: Error413 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 429 | Rate limit exceeded. Retry-After is always present. Quota exhaustion (computed or cached) includes all four X-RateLimit-* headers. The earlier per-key admission-work refusal can omit those quota headers. | application/json: Error429 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.; Retry-After: {"type":"integer"} Seconds until retry. Early admission refusals may omit the quota headers. |
| 500 | Internal error. | application/json: Error500 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 503 | Authentication unavailable. | application/json: Error503 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
DELETE /api/v1/webhooks/{id}
Section titled “DELETE /api/v1/webhooks/{id}”Delete webhook
Accepted authentication: ApiKey or BearerKey.
| Parameter | In | Required | Schema | Description |
|---|---|---|---|---|
id |
path | yes | {"type":"string"} |
| Status | Description | Content type / schema | Headers |
|---|---|---|---|
| 200 | Success | application/json: Message |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 400 | Request rejected. | application/json: Error400 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 401 | Invalid or missing credentials. | application/json: Error401 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 403 | Permission denied. Create lead also returns leads_limit_reached when the storage quota is reached. lead_access_required: an admin without lead access from the workspace owner, on the dashboard or an assistant connection. That admin can still manage API keys, webhooks, scoring rules and the lock policy. API keys never get it. workspace_read_only: the workspace is read-only because its owner owns another Free workspace ranked before it (their first workspace, otherwise the oldest), and only one Free workspace per owner stays editable. Editing resumes when this workspace moves to Pro or Scale, or when its owner no longer owns any Free workspace ranked before it. Every change to leads, scoring rules, the status list and the lock policy is refused, from an API key, the dashboard or an assistant connection. Reading, export, members, API keys, webhooks and assistant connections still work. | application/json: Error403 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.; WWW-Authenticate: {"type":"string"} Present for MCP insufficient_scope. |
| 404 | Request rejected. | application/json: Error404 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 413 | Body exceeds 1 MiB (10 MiB for /leads/batch). | application/json: Error413 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 429 | Rate limit exceeded. Retry-After is always present. Quota exhaustion (computed or cached) includes all four X-RateLimit-* headers. The earlier per-key admission-work refusal can omit those quota headers. | application/json: Error429 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds. Present on computed/cached quota exhaustion; may be absent on earlier admission-work refusal.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers.; Retry-After: {"type":"integer"} Seconds until retry. Early admission refusals may omit the quota headers. |
| 500 | Internal error. | application/json: Error500 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
| 503 | Authentication unavailable. | application/json: Error503 |
X-RateLimit-Limit: {"type":"integer"} Request budget of the binding limit named by X-RateLimit-Scope. Window: 10 minutes. Per credential: Free 250, Pro 2500, Scale 5000. Per account: Free 2500, Pro 62500, Scale 250000, or more when the account keeps more keys and assistant connections than its plan allows.; X-RateLimit-Remaining: {"type":"integer"} Remaining requests in the current window.; X-RateLimit-Reset: {"type":"integer"} Window reset, Unix seconds.; X-RateLimit-Scope: {"type":"string","enum":["credential","account"]} Which limit the other X-RateLimit-* headers describe: credential (the API key, assistant connection or dashboard session) or account. Present with the other X-RateLimit-* headers. |
Schemas and errors
Section titled “Schemas and errors”Schema names in the endpoint tables refer to the definitions below. oneOf means exactly one alternative; anyOf means at least one. Error alternatives list the exact error and code values.
CreateWebhookRequest
Section titled “CreateWebhookRequest”{"type":"object"}
| Field | Required | Schema |
|---|---|---|
url |
yes | {"type":"string","minLength":1,"description":"Public HTTPS delivery URL; unsafe destinations are rejected with 400."} |
events |
no | {"type":["array","null"],"items":{"type":"string"},"description":"Event names to receive. \"*\" receives every lead event. source.silent and source.recovered (lead-flow alerts) are delivered only to a webhook that names them, never through \"*\"."} |
secret |
no | {"type":["string","null"]} |
Deliveries
Section titled “Deliveries”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
deliveries |
yes | {"type":["array","null"],"items":{"$ref":"#/components/schemas/WebhookDelivery"}} |
Error400
Section titled “Error400”{"oneOf":[{"type":"object","properties":{"error":{"const":"bad_request"},"code":{"const":"bad_request"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false},{"type":"object","properties":{"error":{"const":"invalid_scoring_expression"},"code":{"const":"invalid_scoring_expression"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false},{"type":"object","properties":{"error":{"const":"scoring_rules_limit_reached"},"code":{"const":"scoring_rules_limit_reached"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false},{"type":"object","properties":{"error":{"const":"assignee_not_member"},"code":{"const":"assignee_not_member"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}
Error401
Section titled “Error401”{"oneOf":[{"type":"object","properties":{"error":{"const":"unauthorized"},"code":{"const":"unauthorized"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false},{"type":"object","properties":{"error":{"const":"invalid_token"},"code":{"const":"invalid_token"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}
Error403
Section titled “Error403”{"oneOf":[{"type":"object","properties":{"error":{"const":"forbidden"},"code":{"const":"forbidden"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false},{"type":"object","properties":{"error":{"const":"insufficient_scope"},"code":{"const":"insufficient_scope"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false},{"type":"object","properties":{"error":{"const":"leads_limit_reached"},"code":{"const":"leads_limit_reached"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false},{"type":"object","properties":{"error":{"const":"lead_access_required"},"code":{"const":"lead_access_required"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false},{"type":"object","properties":{"error":{"const":"workspace_read_only"},"code":{"const":"workspace_read_only"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}
Error404
Section titled “Error404”{"oneOf":[{"type":"object","properties":{"error":{"const":"not_found"},"code":{"const":"not_found"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}
Error409
Section titled “Error409”{"oneOf":[{"type":"object","properties":{"error":{"const":"conflict"},"code":{"const":"conflict"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}
Error413
Section titled “Error413”{"oneOf":[{"type":"object","properties":{"error":{"const":"payload_too_large"},"code":{"const":"payload_too_large"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}
Error429
Section titled “Error429”{"oneOf":[{"type":"object","properties":{"error":{"const":"rate_limit_exceeded"},"code":{"const":"rate_limit_exceeded"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}
Error500
Section titled “Error500”{"oneOf":[{"type":"object","properties":{"error":{"const":"internal_error"},"code":{"const":"internal_error"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}
Error503
Section titled “Error503”{"oneOf":[{"type":"object","properties":{"error":{"const":"internal_error"},"code":{"const":"internal_error"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}]}
Message
Section titled “Message”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
message |
yes | {"type":"string"} |
UpdateWebhookRequest
Section titled “UpdateWebhookRequest”{"type":"object"}
| Field | Required | Schema |
|---|---|---|
url |
no | {"type":"string","minLength":1,"description":"Public HTTPS delivery URL; unsafe destinations are rejected with 400."} |
events |
no | {"type":"array","items":{"type":"string"}} |
active |
no | {"type":"boolean","description":"false pauses the webhook, true resumes it."} |
secret |
no | {"type":"string","minLength":1,"maxLength":255,"description":"New signing secret, used at once. The replaced secret also signs the Klozeo-Signature header for 24 hours."} |
WebhookDelivery
Section titled “WebhookDelivery”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
id |
yes | {"type":"string"} |
event_id |
yes | {"type":"string"} |
webhook_id |
yes | {"type":"string"} |
event |
yes | {"type":"string"} |
state |
yes | {"type":"string"} |
reason |
yes | {"type":"string","description":"Why the delivery is pending again or dead; empty when delivered or queued for its first attempt.","examples":["transport","retryable_http","permanent_http","unsafe_destination","attempts_exhausted","window_exhausted","paused"]} |
attempts |
yes | {"type":"integer"} |
created_at |
yes | {"type":"string","format":"date-time"} |
next_at |
yes | {"type":"string","format":"date-time"} |
status |
yes | {"type":"integer"} |
redelivery_of |
yes | {"type":["string","null"],"description":"For a manual redelivery, the ID of the original delivery whose event and body it repeats."} |
WebhookResponse
Section titled “WebhookResponse”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
id |
yes | {"type":"string"} |
url |
yes | {"type":"string"} |
events |
yes | {"type":["array","null"],"items":{"type":"string"}} |
active |
yes | {"type":"boolean"} |
created_at |
yes | {"type":"string","format":"date-time"} |
created_by |
yes | {"type":["string","null"],"description":"User ID of the person who created the webhook; null once that person's account is deleted. A webhook created with an API key records the account owner."} |
Webhooks
Section titled “Webhooks”{"type":"object","additionalProperties":false}
| Field | Required | Schema |
|---|---|---|
webhooks |
yes | {"type":["array","null"],"items":{"$ref":"#/components/schemas/WebhookResponse"}} |