Events & delivery behavior

Available webhook events currently include contact_added sms_sent sms_delivered sms_failed call_ringing call_initiated call_answered call_completed voicemail_received. One webhook endpoint can subscribe to any combination of these events.

For Voice API Control flows, use call_ringing together with /api/v1/voice/calls/active and /api/v1/voice/call-control/answer. For SMS delivery reporting, subscribe the same endpoint to sms_sent sms_delivered sms_failed when you want the full lifecycle for each message.

One call event is created for each lifecycle transition. Delivery retries keep the same event ID; ignore repeated event IDs. The final call duration is included with call_completed. For incoming calls with a recorded billing breakdown, call_completed also includes connection_charge_eur and duration_charge_eur. Both are already included in cost_eur; do not add them again. These fields are omitted when the breakdown is unavailable.

For incoming Voice API calls, use data.call.call_id from call_ringing to Answer when can_answer_via_api is true. This is the same public CALL- reference used by active calls. Use the returned call_control_id for subsequent call-control actions.

Delivery is retried after a network/no-response failure and for HTTP 408 429 5xx responses. HTTP 3xx and other 4xx responses stop delivery. The default is up to 8 attempts with exponential delays starting at 30 seconds and capped at one hour, so handlers must tolerate duplicate events.

Use Illyvoip-Delivery as a delivery reference when contacting support. Deduplicate by the event body’s id. Use data.message.message_id to associate an SMS event with the queued_message_ids returned by Send SMS. Do not use the delivery reference as the message ID.

sms_failed reports the delivery outcome, while data.message.status reports the current message/refund state. For a normally charged message, the refund is completed before the event is emitted, so the example has status=refunded, refunded=true, and the refund fields populated.