API reference - Webhook subscriptions and deliveries
API reference · OpenAPI specification
Endpoint definitions below are generated from the API contract. Request and response blocks describe schemas, not example payloads. required lists mandatory fields; $ref refers to a linked model. Send JSON bodies with Content-Type: application/json unless the endpoint specifies binary content.
List this connection's webhook subscriptions
GET /v1/webhook-subscriptions
Requires webhooks.read. Returns all non-deleted subscriptions for this connection, with no pagination or query filters. Signing secrets are never included.
Responses
200 — Connection subscriptions.
application/json
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/Subscription'
rate_limit:
$ref: '#/components/schemas/RateLimit'
Models: Subscription, RateLimit.
Errors — 400 invalid input, 401 expired/revoked/missing key, 403 scope or access denied, 404 missing/inaccessible, 409 request/state conflict, 413 oversized request or response, 415 wrong content type, 429 rate limited, or 503 unavailable. 429 includes Retry-After. All responses include X-Request-Id.
Error format, status codes, and retry guidance.
Subscribe to one or more event types
POST /v1/webhook-subscriptions
Requires webhooks.write plus each selected event's resource read scope. Destinations must use an exact operator-approved HTTPS origin. The default is https://hooks.zapier.com. No redirects are followed. Successful creation and retries return the current subscription and signing secret. A matching active connection/callback/event-set returns its existing subscription and secret. A matching disabled subscription returns 409; deleted tombstones do not block fresh creation.
Parameters
| Name | Location | Required | Description and constraints |
|---|---|---|---|
Idempotency-Key | header | Yes | Use a stable request identifier. Contact writes replay the saved response for seven days, subject to current resource access. Subscription creation retains its identity for seven days but returns current metadata and signing secret; a disabled/deleted subscription rejects replay. Reusing those keys with a different operation, path or exact JSON body returns 409. Subscription status and delete operations are repeatable state changes. Type: string minLength: 8 maxLength: 128 pattern: "^[!-~]+$" |
Request body (required)
application/json
type: object
additionalProperties: false
required:
- target_url
- event_types
properties:
target_url:
type: string
format: uri
maxLength: 2048
event_types:
type: array
minItems: 1
maxItems: 6
items:
$ref: '#/components/schemas/EventType'
Models: EventType.
Responses
201 — Subscription and its private signing secret. Store the secret immediately.
application/json
type: object
required:
- data
properties:
data:
type: object
required:
- subscription
- signing_secret
properties:
subscription:
$ref: '#/components/schemas/Subscription'
signing_secret:
type: string
pattern: ^whsec_
description: whsec_ followed by base64-encoded 32 random bytes.
rate_limit:
$ref: '#/components/schemas/RateLimit'
Models: Subscription, RateLimit.
Errors — 400 invalid input, 401 expired/revoked/missing key, 403 scope or access denied, 404 missing/inaccessible, 409 request/state conflict, 413 oversized request or response, 415 wrong content type, 429 rate limited, or 503 unavailable. 429 includes Retry-After. All responses include X-Request-Id.
Error format, status codes, and retry guidance.
Enable or disable a subscription
PATCH /v1/webhook-subscriptions/{id}
Requires webhooks.write. Event types and destination cannot be changed by this operation.
Parameters
| Name | Location | Required | Description and constraints |
|---|---|---|---|
id | path | Yes | Type: string format: "uuid" |
Idempotency-Key | header | Yes | Use a stable request identifier. Contact writes replay the saved response for seven days, subject to current resource access. Subscription creation retains its identity for seven days but returns current metadata and signing secret; a disabled/deleted subscription rejects replay. Reusing those keys with a different operation, path or exact JSON body returns 409. Subscription status and delete operations are repeatable state changes. Type: string minLength: 8 maxLength: 128 pattern: "^[!-~]+$" |
Request body (required)
application/json
type: object
additionalProperties: false
required:
- status
properties:
status:
type: string
enum:
- active
- disabled
Responses
200 — Subscription metadata, without its secret.
application/json
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/Subscription'
rate_limit:
$ref: '#/components/schemas/RateLimit'
Models: Subscription, RateLimit.
Errors — 400 invalid input, 401 expired/revoked/missing key, 403 scope or access denied, 404 missing/inaccessible, 409 request/state conflict, 413 oversized request or response, 415 wrong content type, 429 rate limited, or 503 unavailable. 429 includes Retry-After. All responses include X-Request-Id.
Error format, status codes, and retry guidance.
Delete a subscription and cancel outstanding deliveries
DELETE /v1/webhook-subscriptions/{id}
Requires webhooks.write. Retains a tombstone and delivery history. A deleted subscription cannot be reactivated.
Parameters
| Name | Location | Required | Description and constraints |
|---|---|---|---|
id | path | Yes | Type: string format: "uuid" |
Idempotency-Key | header | Yes | Use a stable request identifier. Contact writes replay the saved response for seven days, subject to current resource access. Subscription creation retains its identity for seven days but returns current metadata and signing secret; a disabled/deleted subscription rejects replay. Reusing those keys with a different operation, path or exact JSON body returns 409. Subscription status and delete operations are repeatable state changes. Type: string minLength: 8 maxLength: 128 pattern: "^[!-~]+$" |
Responses
200 — Subscription metadata, without its secret.
application/json
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/Subscription'
rate_limit:
$ref: '#/components/schemas/RateLimit'
Models: Subscription, RateLimit.
Errors — 400 invalid input, 401 expired/revoked/missing key, 403 scope or access denied, 404 missing/inaccessible, 409 request/state conflict, 413 oversized request or response, 415 wrong content type, 429 rate limited, or 503 unavailable. 429 includes Retry-After. All responses include X-Request-Id.
Error format, status codes, and retry guidance.
Get setup samples shaped like live webhook events
GET /v1/webhook-samples/{event_type}
Requires the event's resource read scope. Uses accessible real resource data and does not send a webhook or create an event. Sample IDs are prefixed sample_. At most three samples are selected from the 100 most recent accessible resources, newest first. Returns an empty array when no suitable sample is available in that bounded lookup. Static Zapier examples are illustrative only.
Parameters
| Name | Location | Required | Description and constraints |
|---|---|---|---|
event_type | path | Yes | Type: string enum: ["call.completed","call.recording.ready","call.transcript.ready","call.summary.ready","message.received","message.delivered","message.failed","contact.created","contact.updated"] |
inbox_id | query | No | Filter to activity involving this accessible inbox. Does not change connection access or the returned resource projection. Stable existing Waveline record ID. Keep it as a string; it may exceed JavaScript's safe integer range. Type: string maxLength: 19 pattern: "^[1-9][0-9]*$" |
direction | query | No | Filter by external call or message direction. Type: string enum: ["inbound","outbound"] |
recording_type | query | No | Only for call.recording.ready, call.transcript.ready, or call.summary.ready samples. Type: string enum: ["call","voicemail"] |
Responses
200 — Sample event envelopes.
application/json
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/EventEnvelope'
rate_limit:
$ref: '#/components/schemas/RateLimit'
Models: EventEnvelope, RateLimit.
Errors — 400 invalid input, 401 expired/revoked/missing key, 403 scope or access denied, 404 missing/inaccessible, 409 request/state conflict, 413 oversized request or response, 415 wrong content type, 429 rate limited, or 503 unavailable. 429 includes Retry-After. All responses include X-Request-Id.
Error format, status codes, and retry guidance.
Inspect recent webhook delivery outcomes
GET /v1/webhook-deliveries
Requires webhooks.read. Returns the newest limit records without event bodies or secrets. Only limit is supported; no cursor or date filters. Replay is an owner/admin action in the Waveline UI.
Parameters
| Name | Location | Required | Description and constraints |
|---|---|---|---|
limit | query | No | Type: integer default: 50 minimum: 1 maximum: 100 |
Responses
200 — Recent delivery metadata, ordered newest first.
application/json
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/Delivery'
rate_limit:
$ref: '#/components/schemas/RateLimit'
Errors — 400 invalid input, 401 expired/revoked/missing key, 403 scope or access denied, 404 missing/inaccessible, 409 request/state conflict, 413 oversized request or response, 415 wrong content type, 429 rate limited, or 503 unavailable. 429 includes Retry-After. All responses include X-Request-Id.