Appearance
Webhooks
Where Talkline sends what it knows, and what it sent.
List webhook endpoints, newest first
GET /v1/webhooks
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
limit? | query | integer | 1–100. Default 20. |
cursor? | query | string | The nextCursor of the previous page. 1–512 characters. |
Response 200 — A page of endpoints.
| Field | Type | Description |
|---|---|---|
data | WebhookEndpoint[] | |
nextCursor | string | null | The cursor for the next page; null on the last. |
Errors
| Status | Code |
|---|---|
| 400 | validation_failed, token_ttl_too_long |
| 401 | unauthenticated, token_expired, token_replayed, token_not_yet_valid |
| 403 | permission_denied, app_suspended, quota_exhausted |
| 429 | rate_limited |
| 500 | internal |
Register a webhook endpoint
POST /v1/webhooks
https on the public internet only, checked here and again at every delivery attempt; a development deployment can allow http and private addresses (WEBHOOK_ALLOW_PRIVATE). The signing secret is in this response and a rotation's, and nowhere else. A URL already registered is not found again: this makes a second endpoint, and each event then reaches both. At most 16 per application; the seventeenth is 409 conflict.
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute
Request body application/json
| Field | Type | Description |
|---|---|---|
url | string | https, on the public internet. 1–2048 characters. |
events? | string[] | Each one of room.started, room.finished, participant.joined, participant.left, call.ringing, call.answered, call.ended, call.missed, call.rejected, call.cancelled, queue.entered, queue.assigned, queue.abandoned, queue.overflowed, recording.started, recording.finished, recording.failed, usage.threshold, *. 1–19 items. Default ["*"]. |
Response 201 — The endpoint, with its signing secret.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
url | string (uri) | |
events | string[] | * is every event, including those added later. Each one of room.started, room.finished, participant.joined, participant.left, call.ringing, call.answered, call.ended, call.missed, call.rejected, call.cancelled, queue.entered, queue.assigned, queue.abandoned, queue.overflowed, recording.started, recording.finished, recording.failed, usage.threshold, *. |
status | string | failing is the platform's to set, after twenty consecutive failed attempts. One of active, paused, failing. |
createdAt | string (date-time) | |
updatedAt | string (date-time) | |
secret | string | The signing secret — in the answers to registration and rotation, and nowhere else. Matches ^whsec_. |
Errors
Read a webhook endpoint
GET /v1/webhooks/{id}
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id | path | string (uuid) |
Response 200 — The endpoint.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
url | string (uri) | |
events | string[] | * is every event, including those added later. Each one of room.started, room.finished, participant.joined, participant.left, call.ringing, call.answered, call.ended, call.missed, call.rejected, call.cancelled, queue.entered, queue.assigned, queue.abandoned, queue.overflowed, recording.started, recording.finished, recording.failed, usage.threshold, *. |
status | string | failing is the platform's to set, after twenty consecutive failed attempts. One of active, paused, failing. |
createdAt | string (date-time) | |
updatedAt | string (date-time) | |
secret? | string | The signing secret — in the answers to registration and rotation, and nowhere else. Matches ^whsec_. |
Errors
Change an endpoint's URL, events or status
PATCH /v1/webhooks/{id}
Setting active on a paused or failing endpoint is how a human resumes it: its failure streak starts again from nothing, and every delivery it held goes out now, once each.
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id | path | string (uuid) |
Request body application/json
| Field | Type | Description |
|---|---|---|
url? | string | 1–2048 characters. |
events? | string[] | Each one of room.started, room.finished, participant.joined, participant.left, call.ringing, call.answered, call.ended, call.missed, call.rejected, call.cancelled, queue.entered, queue.assigned, queue.abandoned, queue.overflowed, recording.started, recording.finished, recording.failed, usage.threshold, *. 1–19 items. |
status? | string | active resumes a paused or failing endpoint. One of active, paused. |
Response 200 — The endpoint, as it now stands.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
url | string (uri) | |
events | string[] | * is every event, including those added later. Each one of room.started, room.finished, participant.joined, participant.left, call.ringing, call.answered, call.ended, call.missed, call.rejected, call.cancelled, queue.entered, queue.assigned, queue.abandoned, queue.overflowed, recording.started, recording.finished, recording.failed, usage.threshold, *. |
status | string | failing is the platform's to set, after twenty consecutive failed attempts. One of active, paused, failing. |
createdAt | string (date-time) | |
updatedAt | string (date-time) | |
secret? | string | The signing secret — in the answers to registration and rotation, and nowhere else. Matches ^whsec_. |
Errors
Remove an endpoint, with its deliveries
DELETE /v1/webhooks/{id}
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id | path | string (uuid) |
Response 204 — Removed.
Errors
Rotate an endpoint's signing secret
POST /v1/webhooks/{id}/secret
Every attempt from now on is signed with the new secret, retries included.
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id | path | string (uuid) |
Response 200 — The endpoint, with its new secret.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
url | string (uri) | |
events | string[] | * is every event, including those added later. Each one of room.started, room.finished, participant.joined, participant.left, call.ringing, call.answered, call.ended, call.missed, call.rejected, call.cancelled, queue.entered, queue.assigned, queue.abandoned, queue.overflowed, recording.started, recording.finished, recording.failed, usage.threshold, *. |
status | string | failing is the platform's to set, after twenty consecutive failed attempts. One of active, paused, failing. |
createdAt | string (date-time) | |
updatedAt | string (date-time) | |
secret | string | The signing secret — in the answers to registration and rotation, and nowhere else. Matches ^whsec_. |
Errors
The endpoint's delivery log, newest first
GET /v1/webhooks/{id}/deliveries
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id | path | string (uuid) | |
limit? | query | integer | 1–100. Default 20. |
cursor? | query | string | The nextCursor of the previous page. 1–512 characters. |
status? | query | string | One of pending, delivered, failed, abandoned. |
Response 200 — A page of deliveries.
| Field | Type | Description |
|---|---|---|
data | Delivery[] | |
nextCursor | string | null | The cursor for the next page; null on the last. |
Errors