Webhooks

LiveSwitch webhooks notify your application when LiveSwitch creates, updates, or deletes supported resources.

Creating and managing webhooks

To create a webhook through the API, use the Create a webhook endpoint.

Webhook management applies across the organization. Users who manage webhooks must have the appropriate organization permissions.

Webhook operations require these OAuth scopes:

• The webhooks scope permits retrieval of webhooks
• The webhooks.write scope permits creation, updates, or deletion of webhooks.

The webhook URL must be a valid HTTP or HTTPS URL with public access. LiveSwitch does not accept localhost, private network addresses, link-local addresses, or internal hostnames.

Supported entities and events

These entities support the listed 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. For new integrations, use Contacts.

Event payloads

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

If you need the latest complete resource for CREATE or UPDATE events, use its GET endpoint. For DELETE events, the resource can become unavailable through its GET endpoint.

Event headers

Each webhook request includes these headers:

• The x-liveswitch-transaction-id header identifies the transaction that triggered the event. Multiple related webhook deliveries can share a transaction ID.
• The x-liveswitch-entity-id header contains the ID of the resource that LiveSwitch created, updated, or deleted.
• The x-liveswitch-webhook-id header contains the ID of the webhook subscription that LiveSwitch invokes.
• The x-liveswitch-webhook-event-type header contains the event type: CREATE, UPDATE, or DELETE.
• The x-liveswitch-webhook-entity-name header contains the lowercase identifier for the affected entity, such as contact, conversation, or account.

To correlate deliveries, use both the webhook ID and transaction ID. One transaction ID does not necessarily represent only one webhook request.