Webhooks

Webhooks let you receive real-time HTTP notifications when events occur in your VOCALS tenant. Configure a URL and subscribe to specific event types; VOCALS will POST a JSON payload to your endpoint whenever a matching event fires.

Event Types

Event	Description
call.started	A call has started (inbound or outbound)
call.ended	A call has ended
transcript.ready	The full transcript for a call is available

List Webhooks

GET /webhooks

Returns all webhook configurations for the current tenant, ordered by creation date.

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://example.com/vocals-webhook",
    "events": ["call.started", "call.ended"],
    "is_active": true,
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-20T14:00:00Z"
  }
]

Response Fields

Field	Type	Description
id	uuid	Webhook config ID
url	string	Destination URL for event payloads
events	array	List of subscribed event types
is_active	boolean	Whether the webhook is active
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Create Webhook

POST /webhooks

Request Body

{
  "url": "https://example.com/vocals-webhook",
  "events": ["call.started", "call.ended", "transcript.ready"],
  "is_active": true
}

Request Fields

Field	Type	Required	Default	Description
url	string	Yes	--	HTTPS URL to receive webhook payloads
events	array	Yes	--	Event types to subscribe to
is_active	boolean	No	true	Whether the webhook is active

Response

201 Created -- Returns the WebhookResponse object.

Update Webhook

PUT /webhooks/{webhook_id}

Partial updates are supported. Only include the fields you want to change.

Request Body

{
  "url": "https://new-url.example.com/webhook",
  "events": ["call.ended"],
  "is_active": false
}

Request Fields

Field	Type	Required	Description
url	string	No	Updated destination URL
events	array	No	Updated event subscriptions
is_active	boolean	No	Enable or disable the webhook

Response

200 OK -- Returns the updated WebhookResponse.

Delete Webhook

DELETE /webhooks/{webhook_id}

Permanently deletes a webhook configuration and its delivery history.

Response

204 No Content

Delivery Logs

GET /webhooks/{webhook_id}/deliveries

Returns a paginated list of delivery attempts for a specific webhook, ordered by most recent first. Use this to troubleshoot failed deliveries.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
page_size	integer	20	Items per page (max 100)

Response

{
  "items": [
    {
      "id": "660e8400-...",
      "event_type": "call.ended",
      "status_code": 200,
      "attempts": 1,
      "last_attempt_at": "2026-03-01T14:32:50Z",
      "created_at": "2026-03-01T14:32:45Z"
    },
    {
      "id": "770e8400-...",
      "event_type": "call.started",
      "status_code": 500,
      "attempts": 3,
      "last_attempt_at": "2026-03-01T14:31:15Z",
      "created_at": "2026-03-01T14:30:05Z"
    }
  ],
  "total": 85,
  "page": 1,
  "page_size": 20
}

Delivery Log Fields

Field	Type	Description
id	uuid	Delivery log ID
event_type	string	The event that triggered this delivery
status_code	integer | null	HTTP status code from the webhook endpoint (null if no response)
attempts	integer	Number of delivery attempts
last_attempt_at	datetime | null	Timestamp of the most recent attempt
created_at	datetime	When the delivery was first triggered