Receive IllyVoIP voicemail notifications in your application

Subscribe your application to voicemail_received when it needs to react to a newly detected IllyVoIP voicemail—for example, by creating a follow-up task for the responsible team. The event carries message metadata and a Portal playback link. It does not make the recording a public file.

Before you start

You need permission to manage the account’s webhooks, a server-side HTTPS receiver, the endpoint signing secret and a durable place to record processed events. Keep that secret on your server. Choose who may see caller details and which application should own the resulting task before enabling notifications.

1. Subscribe and authenticate the delivery

1. Open the Portal API webhook settings, configure your HTTPS endpoint and select the voicemail event. Use the signing secret associated with that endpoint.
2. At the receiver, preserve the exact raw request body before JSON decoding. Validate the Illyvoip-Signature header using the documented HMAC-SHA256 scheme over the timestamp, a period and the raw body.
3. Apply the documented timestamp tolerance and keep your server clock synchronized. Use the signature timestamp for delivery authentication, not the voicemail’s original received time.
4. Reject invalid signatures before creating a task or following any link. Never accept an unsigned request merely because its JSON resembles the example below.

2. Read the voicemail object

This abbreviated example illustrates fields inside the event payload. The surrounding webhook envelope also supplies the event ID and event type. Identifiers and values below are examples; save the actual identifiers received by your endpoint.

{
  "voicemail": {
    "owner_user_id": 123,
    "mailbox": "mailbox-example",
    "message_id": "message-example",
    "received_at": "2026-10-12 12:00:00",
    "duration_seconds": 24,
    "from_number": "+12025550123",
    "media": {
      "content_type": "audio/wav",
      "portal_playback_url": "https://app.illyvoip.com/portal/voicemail/play?mailbox=mailbox-example&message_id=message-example"
    }
  }
}

Use the mailbox and message identity to associate follow-up work with the right voicemail. The payload can also include caller-name, caller-ID and agent metadata. Treat absent or empty optional values as unknown. Do not expect an agent email to be populated, and do not substitute a voicemail message ID for a Voice API call-control ID.

3. Deduplicate before creating follow-up work

1. Record the webhook envelope ID under a unique constraint so a retried delivery cannot create a second task.
2. Persist the verified event and the intended work durably before returning a successful response. If that write fails, do not acknowledge a task you have not saved.
3. Process the saved event in your worker. Use the account, mailbox and message identity when correlating the same voicemail across your own records.
4. If downstream task creation has an uncertain result, reconcile it using your saved identity before creating another task. Delivery deduplication alone does not make a separate task system exactly-once.

4. Keep playback inside authorized access

The supplied Portal playback URL requires the appropriate authenticated Portal access. Show it to authorized staff as a link to the message; do not treat it as a bearer download URL for an unauthenticated bot. Do not copy browser session cookies into your worker or publish the link and caller metadata in a public channel. A received event is not proof that audio will remain accessible indefinitely or that the current viewer has access.

Check and troubleshoot the workflow

Test signature validation and duplicate handling locally using synthetic messages first. For an authorized real-message check, compare the saved event with the voicemail visible to the intended Portal user, then confirm one follow-up task was created. Do not infer a missed event solely from an empty email field. Check the subscription, receiver response, signing secret and durable event record. Keep event and message references for Support, with caller data and secrets removed.

Related guides

• Find and listen to voicemail
• Verify IllyVoIP webhook signatures in a Node.js receiver
• Receive and verify IllyVoIP webhooks in Python with FastAPI
• Troubleshoot webhook delivery

Reviewed 12 October 2026 against the current IllyVoIP controls, implementation and applicable references. Available options depend on account permissions and service state.