Webhooks

Webhooks and their deliveries.

GET/v1/webhooks

Create a webhook

createWebhookwebhooks:managewrite: 120/min per keyIdempotency-Key

Registers a signed webhook for sendable event types (GET /v1/event-types) or "*". The address must be a public https one; it is checked again before every delivery, and redirects are never followed. Deliveries are written in the contract this request runs in. The signing secret is returned once. includeConversation: true needs a key holding transcripts:read; transcript.final needs it and must be named. While the organisation has zero data retention on, includeConversation: true is refused (409 conflict, details.reason zero_retention).

Body

urlstringrequired
A public https address. Private and local addresses are refused; redirects are never followed.
at most 2,048 characters
eventsstring[]
Event types, or ["*"] (the default). transcript.final needs includeConversation: true.
at most 100 items
descriptionstring
at most 200 characters
includeConversationboolean
Send conversation words to this webhook where Zentiq's privacy rules allow them: transcript.final (sessions your app started through the API, and only when named in events), session.ended's and report.produced's summaries, report feedback lines and quotes, a visitor's own words (need, budget, timeline, a lead's answers, a hand-off's summary and reason), a rating's comment, knowledge.gap's questions and case_link.opened's case summary. Never from a child's, a candidate's (any hiring session), a practice, a held or a safety-flagged session. Off by default. Turning it on needs a key holding transcripts:read; every change is recorded in the organisation's activity log. Refused, and off, while the organisation has zero data retention on.

Returns

201 Created; the secret is shown once. data is WebhookWithSecret.

Fields of data

idstringrequired
Webhook id (wh_…).
pattern `^wh_.*`
urlstringrequired
Where deliveries go: a public https address, checked again before every attempt.
descriptionstring | nullrequired
eventsstring[]required
The event types it receives; ["*"] = every type except transcript.final, which must be named.
includeConversationbooleanrequired
Send conversation words to this webhook where Zentiq's privacy rules allow them: transcript.final (sessions your app started through the API, and only when named in events), session.ended's and report.produced's summaries, report feedback lines and quotes, a visitor's own words (need, budget, timeline, a lead's answers, a hand-off's summary and reason), a rating's comment, knowledge.gap's questions and case_link.opened's case summary. Never from a child's, a candidate's (any hiring session), a practice, a held or a safety-flagged session. Off by default. Turning it on needs a key holding transcripts:read; every change is recorded in the organisation's activity log. Refused, and off, while the organisation has zero data retention on.
activebooleanrequired
False while switched off, and after three days of failed deliveries (then pausedAt says when).
pausedAtstring (date-time) | nullrequired
When it was paused after failing every delivery for three days; PATCH { active: true } resumes it.
apiVersion"2026-07-08" | "2026-10-01"required
The contract its deliveries are written in (the creating key's; PATCH to move it).
createdAtstring (date-time)required
ISO 8601 UTC timestamp.
updatedAtstring (date-time)required
ISO 8601 UTC timestamp.
secretstringrequired
The signing secret: returned once, at creation.

Errors

invalid_request unauthorized forbidden upgrade_required conflict idempotency_conflict idempotency_in_progress rate_limited server_error

Request

curl -X POST "https://app.zentiqai.com/v1/webhooks" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://www.example.com"
}'

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.createWebhook({
  url: "https://www.example.com",
});

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.create_webhook({
    "url": "https://www.example.com",
})

Example answer

Response

{
  "data": {
    "id": "wh_cmfq2b7x10000abcd1234",
    "url": "https://www.example.com",
    "description": "…",
    "events": [
      "…"
    ],
    "includeConversation": true,
    "active": true
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

GET/v1/webhooks/{id}

Get a webhook

getWebhookwebhooks:manageread: 600/min per keySince 2026-10-01

Path parameters

idstringrequired
Webhook id (wh_…); the id without its prefix is accepted too.

Returns

200 The webhook. data is Webhook.

Fields of data

idstringrequired
Webhook id (wh_…).
pattern `^wh_.*`
urlstringrequired
Where deliveries go: a public https address, checked again before every attempt.
descriptionstring | nullrequired
eventsstring[]required
The event types it receives; ["*"] = every type except transcript.final, which must be named.
includeConversationbooleanrequired
Send conversation words to this webhook where Zentiq's privacy rules allow them: transcript.final (sessions your app started through the API, and only when named in events), session.ended's and report.produced's summaries, report feedback lines and quotes, a visitor's own words (need, budget, timeline, a lead's answers, a hand-off's summary and reason), a rating's comment, knowledge.gap's questions and case_link.opened's case summary. Never from a child's, a candidate's (any hiring session), a practice, a held or a safety-flagged session. Off by default. Turning it on needs a key holding transcripts:read; every change is recorded in the organisation's activity log. Refused, and off, while the organisation has zero data retention on.
activebooleanrequired
False while switched off, and after three days of failed deliveries (then pausedAt says when).
pausedAtstring (date-time) | nullrequired
When it was paused after failing every delivery for three days; PATCH { active: true } resumes it.
apiVersion"2026-07-08" | "2026-10-01"required
The contract its deliveries are written in (the creating key's; PATCH to move it).
createdAtstring (date-time)required
ISO 8601 UTC timestamp.
updatedAtstring (date-time)required
ISO 8601 UTC timestamp.

Errors

invalid_request unauthorized forbidden upgrade_required not_found rate_limited server_error

Request

curl "https://app.zentiqai.com/v1/webhooks/wh_123" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY"

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.getWebhook("wh_123");

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.get_webhook("wh_123")

Example answer

Response

{
  "data": {
    "id": "wh_cmfq2b7x10000abcd1234",
    "url": "https://www.example.com",
    "description": "…",
    "events": [
      "…"
    ],
    "includeConversation": true,
    "active": true
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

PATCH/v1/webhooks/{id}

Change a webhook

updateWebhookwebhooks:managewrite: 120/min per keySince 2026-10-01

Change its address, events, description, contract or conversation option; active: true resumes a webhook paused after three days of failed deliveries, false switches it off. Turning includeConversation on needs transcripts:read, and so does changing the address, events or contract of a webhook that receives conversation words, or switching it back on (switching the words off never does); every change of the option is recorded in the organisation's activity log. While the organisation has zero data retention on, any change that leaves includeConversation on is refused (409 conflict, details.reason zero_retention); switching it off always works.

Path parameters

idstringrequired
Webhook id (wh_…); the id without its prefix is accepted too.

Body

urlstring
at most 2,048 characters
eventsstring[]
at most 100 items
descriptionstring | null
activeboolean
true resumes a paused webhook (its failing run starts again); false switches it off.
apiVersion"2026-07-08" | "2026-10-01"
Move its deliveries to another contract.
includeConversationboolean
Send conversation words to this webhook where Zentiq's privacy rules allow them: transcript.final (sessions your app started through the API, and only when named in events), session.ended's and report.produced's summaries, report feedback lines and quotes, a visitor's own words (need, budget, timeline, a lead's answers, a hand-off's summary and reason), a rating's comment, knowledge.gap's questions and case_link.opened's case summary. Never from a child's, a candidate's (any hiring session), a practice, a held or a safety-flagged session. Off by default. Turning it on needs a key holding transcripts:read; every change is recorded in the organisation's activity log. Refused, and off, while the organisation has zero data retention on.

Returns

200 The webhook as changed. data is Webhook.

Fields of data

idstringrequired
Webhook id (wh_…).
pattern `^wh_.*`
urlstringrequired
Where deliveries go: a public https address, checked again before every attempt.
descriptionstring | nullrequired
eventsstring[]required
The event types it receives; ["*"] = every type except transcript.final, which must be named.
includeConversationbooleanrequired
Send conversation words to this webhook where Zentiq's privacy rules allow them: transcript.final (sessions your app started through the API, and only when named in events), session.ended's and report.produced's summaries, report feedback lines and quotes, a visitor's own words (need, budget, timeline, a lead's answers, a hand-off's summary and reason), a rating's comment, knowledge.gap's questions and case_link.opened's case summary. Never from a child's, a candidate's (any hiring session), a practice, a held or a safety-flagged session. Off by default. Turning it on needs a key holding transcripts:read; every change is recorded in the organisation's activity log. Refused, and off, while the organisation has zero data retention on.
activebooleanrequired
False while switched off, and after three days of failed deliveries (then pausedAt says when).
pausedAtstring (date-time) | nullrequired
When it was paused after failing every delivery for three days; PATCH { active: true } resumes it.
apiVersion"2026-07-08" | "2026-10-01"required
The contract its deliveries are written in (the creating key's; PATCH to move it).
createdAtstring (date-time)required
ISO 8601 UTC timestamp.
updatedAtstring (date-time)required
ISO 8601 UTC timestamp.

Errors

invalid_request unauthorized forbidden upgrade_required not_found conflict rate_limited server_error

Request

curl -X PATCH "https://app.zentiqai.com/v1/webhooks/wh_123" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.updateWebhook("wh_123", {});

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.update_webhook("wh_123", {})

Example answer

Response

{
  "data": {
    "id": "wh_cmfq2b7x10000abcd1234",
    "url": "https://www.example.com",
    "description": "…",
    "events": [
      "…"
    ],
    "includeConversation": true,
    "active": true
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

DELETE/v1/webhooks/{id}

Delete a webhook

deleteWebhookwebhooks:managewrite: 120/min per key

Deletes the webhook and its delivery log.

Path parameters

idstringrequired
Webhook id (wh_…); the id without its prefix is accepted too.

Returns

200 Deleted. data is WebhookDeleted.

Fields of data

deletedtruerequired
idstringrequired
Webhook id (wh_…).
pattern `^wh_.*`

Errors

invalid_request unauthorized forbidden upgrade_required not_found rate_limited server_error

Request

curl -X DELETE "https://app.zentiqai.com/v1/webhooks/wh_123" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY"

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.deleteWebhook("wh_123");

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.delete_webhook("wh_123")

Example answer

Response

{
  "data": {
    "deleted": true,
    "id": "wh_cmfq2b7x10000abcd1234"
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

GET/v1/webhooks/deliveries

The delivery log

webhookDeliverieswebhooks:manageread: 600/min per key

Each event's delivery to each webhook, newest first, with its last attempt and, while it is retried, the next one (1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h after the first). Filter by webhook, event, state, success and time.

Query parameters

limitinteger
Page size, 1-200 (default 50).
cursorstring
The nextCursor of the previous page.
webhookIdstring
Webhook id (wh_…).
eventIdstring
Event id (evt_…).
statestring
One or more of pending, retrying, delivered, failed, comma-separated.
ok"true" | "false"
fromstring
Deliveries created at or after this moment.
tostring
Deliveries created before this moment.

Returns

200 A page of deliveries. A page: data is a list of WebhookDelivery, and nextCursor fetches the next page.

Fields of data

idstringrequired
whd_… (sent as X-Zentiq-Delivery-Id). Keys on the 2026-07-08 contract receive the id without its prefix.
webhookIdstringrequired
Webhook id (wh_…).
pattern `^wh_.*`
eventIdstring | nullrequired
The event delivered (evt_…, the envelope's id); null for deliveries logged before the outbox.
eventstringrequired
The event's type.
state"pending" | "retrying" | "delivered" | "failed"required
pending (the first attempt is under way), retrying (the next attempt is at nextAttemptAt), delivered, failed (no attempt left, or closed: see errorCode).
attemptsintegerrequired
statusinteger | nullrequired
The HTTP status of the last attempt; null when none was reached.
okbooleanrequired
responseMsinteger | nullrequired
errorCodestring | nullrequired
Why the last attempt failed or the delivery closed: http_status, redirect, timeout, network, address_refused, internal_error, webhook_inactive, webhook_paused, unsubscribed, withdrawn, event_gone.
nextAttemptAtstring (date-time) | nullrequired
createdAtstring (date-time)required
ISO 8601 UTC timestamp.

Errors

invalid_request unauthorized forbidden upgrade_required rate_limited server_error

Request

curl "https://app.zentiqai.com/v1/webhooks/deliveries?limit=20" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY"

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const page = await zentiq.webhookDeliveries({
  limit: 20,
});

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
page = zentiq.webhook_deliveries(limit=20)

Example answer

Response

{
  "data": [
    {
      "id": "whd_123",
      "webhookId": "wh_cmfq2b7x10000abcd1234",
      "eventId": "evt_cmfq2b7x10000abcd1234",
      "event": "…",
      "state": "pending",
      "attempts": 1
    }
  ],
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d",
  "nextCursor": null
}

List webhooks

Query parameters

Returns

Errors

Request

Create a webhook

Body

Returns

Errors

Request

Get a webhook

Path parameters

Returns

Errors

Request

Change a webhook

Path parameters

Body

Returns

Errors

Request

Delete a webhook

Path parameters

Returns

Errors

Request

The delivery log

Query parameters

Returns

Errors

Request