Webhooks

LiveSwitch webhooks notify your application when supported resources are created, updated, or deleted.

Creating and managing webhooks

Create a webhook programmatically using the Create a webhook endpoint.

Webhook management is organization-wide. Users managing webhooks must have the appropriate organization permissions.

The following OAuth scopes are required:

• webhooks to retrieve webhooks
• webhooks.write to create, update, or delete webhooks

The webhook URL must be a valid, publicly accessible HTTP or HTTPS URL. Localhost, private network addresses, link-local addresses, and internal hostnames are not accepted.

Supported entities and events

• Contacts: CREATE, UPDATE, DELETE
• Conversations: CREATE, UPDATE, DELETE
• Accounts: CREATE, UPDATE, DELETE
• AppInstallations: CREATE, DELETE
• Recordings: CREATE, UPDATE, DELETE
• Documents: CREATE, UPDATE, DELETE

Customers is a legacy alias for Contacts. New integrations should use Contacts.

Event payloads

Webhook payloads do not always contain every property of the affected resource. The resource ID is included in the payload and in the x-liveswitch-entity-id header.

For CREATE and UPDATE events, use the corresponding GET endpoint if you need the latest complete resource. For DELETE events, the resource may no longer be available through its GET endpoint.

Event headers

Each webhook request includes the following headers:

• x-liveswitch-transaction-id: Identifies the underlying transaction that triggered the event. Multiple related webhook deliveries may share a transaction ID.
• x-liveswitch-entity-id: The ID of the resource that was created, updated, or deleted.
• x-liveswitch-webhook-id: The ID of the webhook subscription being invoked.
• x-liveswitch-webhook-event-type: The event type: CREATE, UPDATE, or DELETE.
• x-liveswitch-webhook-entity-name: The lowercase identifier for the affected entity, such as contact, conversation, or account.

Webhook consumers should use both the webhook ID and transaction ID when correlating deliveries rather than assuming that a transaction ID represents only one webhook request."contact" or "conversation"