Webhooks API

How LiveVoice Webhooks Work

LiveVoice allows you to register webhooks that notify your application when certain events happen.

Webhooks are sent to your endpoint with a POST request. If the endpoint is not reachable we will retry 3 times (with an exponential backoff). After all retries failed, we will send you an email that the webhook notification failed.

Webhook Signature Verification

We highly recommend verifying those messages with their HMAC signature. This way you can be sure that your received messages have been authored by LiveVoice and has not been tampered. Here is the expression that has to evaluate to true:

secure_compare(HMAC_SHA256(secret, "{timestamp}.{raw_body}"), signature)

where "secret" is the secret you set when creating the webhook, "timestamp" is read from the header "Webhook-Timestamp" and signature is from the header "Webhook-Signature". Both headers are sent with every webhook message:

• Webhook-Signature is lowercase hex-encoded HMAC-SHA256
• Webhook-Timestamp is a Unix epoch (seconds), matching the value used in the signature
  

Webhook Event Ordering and Replay Protection

Note, that it is not guaranteed that you will receive webhook calls in order. For that reason we include "occurred_at" datetime strings into every sent webhook message. That way, you can throw away messages that are outdated (to make sure you don't update internal states that are stale).

To prevent replay attacks, you can throw away messages that have a "Webhook-Timestamp" header longer than 5 minutes ago.

Webhook Notification Structure

Our webhook notifications have this structure:

{
  "id": "6b948d5e-4231-461a-9810-f832783afc40",
  "event": "channel_state_changed",
  "occurred_at": "2026-08-23T19:06:41.003+02:00",
  "sent_at": "2026-08-23T19:06:41.107+02:00",
  "data": {
    ...
  }
}

where "occurred_at" and "sent_at" are ISO 8601 datetime strings and data contains the payload of the specific webhook event.

List webhooks

Lists all your configured webhooks.

Endpoint:

• [GET] https://livevoice.io/api/v2/webhooks

Create webhook

Creates a new webhook that will notify your application if a certain event happens.

Endpoint:

• [POST] https://livevoice.io/api/v2/webhooks

Params:

• event (subscribable event string, see list below for subscribable events)
• secret (a secret string that has at least 32 characters)
• url (the URL string that LiveVoice should call when the event happens)

Subscribable events:

• channel_state_changed: Get notified whenever a channel state changed. Possible channel states are: 'offline', 'speaking', 'ai_translating', 'importing_source', 'importing_channel'. An example payload: { "channel_id": 1234, "old_state": "offline", "new_state": "speaking" }

Errors:

• [422] too_many_webhooks (exceeded the account's webhook limit)
• [422] invalid_params (missing or wrong parameters)

Delete webhook

Deletes one of your webhooks.

Endpoint:

• [DELETE] https://livevoice.io/api/v2/webhooks/:id

URL Params:

• id (the webhook ID)

Errors:

• [404] not_found (provided webhook ID was invalid)