Webhooks
WhatsApp message events
Receive incoming-message and delivery updates for your connected WhatsApp numbers.
Configure your endpoint
Open Account Settings → Integrations / CRM & webhooks, create an HTTPS endpoint and subscribe to the WhatsApp events you need. Save the signing secret securely. The endpoint belongs to your IllyVoIP account; it is separate from the Meta delivery destination managed by IllyVoIP.
Event types
| Event | Meaning |
|---|---|
whatsapp_received | An incoming message was saved. |
whatsapp_sent | Meta reported sent; this does not confirm delivery. |
whatsapp_delivered | Delivery was confirmed. |
whatsapp_read | Meta reported read; availability depends on recipient settings. |
whatsapp_failed | A failure was confirmed. |
Payload and message content
The JSON envelope contains id, type, created_at and data. Data contains message_id, number_id, direction, recipient, type, status, settlement_state, platform_fee, currency and updated_at. For incoming messages, recipient identifies the remote customer. Message text and media bytes are not included. Retrieve owned content with GET /api/v1/whatsapp/messages/status?message_id=... and attachments with GET /api/v1/whatsapp/messages/attachment?message_id=....
Verify and acknowledge
Verify Illyvoip-Signature against the exact raw body: HMAC-SHA256 of timestamp + "." + raw_body, using your endpoint secret. The header is t=timestamp,v1=hex_digest. Illyvoip-Event identifies the event type; Illyvoip-Delivery identifies its delivery job. Persist accepted events before returning a 2xx response. Deduplicate using the envelope event ID; process asynchronously. Use the shared signature-verification reference for a complete receiver example.
Ordering and billing
Events can be retried or arrive out of order. Do not assume every intermediate status will be delivered; retrieve current message state when reconciling. The event fee/settlement fields are a snapshot and may precede settlement completion. Incoming messages are free; IllyVoIP charges its platform fee only for delivered outbound messages. Meta billing is separate. An uncertain send must not be repeated under a new idempotency key.
Signature verification and receiver example