Webhook Events Reference
Complete reference for all webhook events sent by Vobiz, including payload structures and example data for each event type.
Event Payload Format
All webhook events follow a consistent JSON structure with common fields and event-specific data. Events are sent as HTTP POST requests with Content-Type: application/json.
Common Event Structure
All webhook events share these common fields:
{
"event": "event.type",
"event_id": "evt_1234567890abcdef",
"timestamp": "2024-03-19T10:30:00Z",
"channel_id": "ch_abc123",
"data": {
// Event-specific data
}
}Common Fields
| Field | Type | Description |
|---|---|---|
| event | string | The event type (e.g., "message.received") |
| event_id | string | Unique identifier for this event (use for deduplication) |
| timestamp | string | ISO 8601 timestamp when the event occurred |
| channel_id | string | ID of the WhatsApp channel this event relates to |
| data | object | Event-specific payload data |
message.received
Triggered when your business receives a message from a customer. This is the most common event and is essential for building conversational experiences.
Text Message Example
{
"event": "message.received",
"event_id": "evt_msg_recv_123",
"timestamp": "2024-03-19T10:30:45Z",
"channel_id": "ch_abc123",
"data": {
"message_id": "wamid.HBgNMTIzNDU2Nzg5MAA=",
"from": "+1234567890",
"contact": {
"id": "cnt_xyz789",
"name": "John Doe",
"phone": "+1234567890"
},
"type": "text",
"text": {
"body": "Hello, I have a question about my order"
},
"timestamp": "2024-03-19T10:30:45Z",
"context": null
}
}Image Message Example
{
"event": "message.received",
"event_id": "evt_msg_recv_124",
"timestamp": "2024-03-19T10:31:00Z",
"channel_id": "ch_abc123",
"data": {
"message_id": "wamid.HBgNMTIzNDU2Nzg5MABB",
"from": "+1234567890",
"contact": {
"id": "cnt_xyz789",
"name": "John Doe",
"phone": "+1234567890"
},
"type": "image",
"image": {
"id": "img_123456",
"mime_type": "image/jpeg",
"sha256": "abc123def456...",
"caption": "Product I received"
},
"timestamp": "2024-03-19T10:31:00Z"
}
}Supported Message Types
- •
text- Plain text messages - •
image- Images with optional caption - •
video- Videos with optional caption - •
audio- Voice messages or audio files - •
document- PDF, Word, Excel, etc. - •
location- Shared location with coordinates - •
contacts- Shared contact cards - •
button- Button click response - •
interactive- List or button selections
💡 Use Case
Use this event to create support tickets, route inquiries to agents, trigger chatbots, or log customer conversations in your CRM.
message.sent
Triggered when a message is successfully sent from your business to a customer. This confirms the message has been accepted by WhatsApp's servers.
{
"event": "message.sent",
"event_id": "evt_msg_sent_125",
"timestamp": "2024-03-19T10:32:00Z",
"channel_id": "ch_abc123",
"data": {
"message_id": "wamid.HBgNMTIzNDU2Nzg5MCC=",
"to": "+1234567890",
"type": "text",
"status": "sent",
"timestamp": "2024-03-19T10:32:00Z"
}
}💡 Use Case
Use this event to update message status in your UI, log outbound messages for compliance, or track when automated messages are sent.
message.delivered
Triggered when a sent message is successfully delivered to the recipient's device. This shows as double gray checkmarks in WhatsApp.
{
"event": "message.delivered",
"event_id": "evt_msg_dlv_126",
"timestamp": "2024-03-19T10:32:05Z",
"channel_id": "ch_abc123",
"data": {
"message_id": "wamid.HBgNMTIzNDU2Nzg5MCC=",
"to": "+1234567890",
"status": "delivered",
"timestamp": "2024-03-19T10:32:05Z"
}
}⚠️ Note
Delivery doesn't guarantee the message was read, only that it reached the recipient's phone. The message may still be unread in their WhatsApp inbox.
message.read
Triggered when a recipient opens and reads your message. This shows as blue double checkmarks in WhatsApp (if the recipient has read receipts enabled).
{
"event": "message.read",
"event_id": "evt_msg_read_127",
"timestamp": "2024-03-19T10:35:30Z",
"channel_id": "ch_abc123",
"data": {
"message_id": "wamid.HBgNMTIzNDU2Nzg5MCC=",
"to": "+1234567890",
"status": "read",
"timestamp": "2024-03-19T10:35:30Z"
}
}💡 Use Case
Use this event to calculate campaign read rates, notify sales teams when prospects read messages, or trigger follow-up workflows.
⚠️ Privacy Note
Users can disable read receipts in WhatsApp settings. If disabled, you won't receive read events even if they've read the message.
message.failed
Triggered when a message fails to send. The event includes error details explaining why delivery failed.
{
"event": "message.failed",
"event_id": "evt_msg_fail_128",
"timestamp": "2024-03-19T10:32:10Z",
"channel_id": "ch_abc123",
"data": {
"message_id": "wamid.HBgNMTIzNDU2Nzg5MDD=",
"to": "+9999999999",
"status": "failed",
"error": {
"code": "INVALID_NUMBER",
"message": "Phone number not registered on WhatsApp",
"details": "The recipient number is not a valid WhatsApp account"
},
"timestamp": "2024-03-19T10:32:10Z"
}
}Common Error Codes
INVALID_NUMBER
Phone number is not registered on WhatsApp
BLOCKED
Recipient has blocked your business number
RATE_LIMIT
Messaging rate limit exceeded
TEMPLATE_NOT_FOUND
Template doesn't exist or isn't approved
PARAMETER_ERROR
Invalid template parameters provided
💡 Use Case
Use this event to alert users about failed sends, clean invalid numbers from your contact list, or trigger fallback communication channels (email, SMS).
contact.updated
Triggered when a contact is created or updated in Vobiz. This includes changes to contact details, tags, or custom attributes.
{
"event": "contact.updated",
"event_id": "evt_cnt_upd_129",
"timestamp": "2024-03-19T11:00:00Z",
"channel_id": "ch_abc123",
"data": {
"contact": {
"id": "cnt_xyz789",
"phone": "+1234567890",
"name": "John Doe",
"email": "john@example.com",
"tags": ["customer", "vip"],
"custom_attributes": {
"customer_id": "CUST-001",
"total_orders": 5
},
"created_at": "2024-01-15T09:00:00Z",
"updated_at": "2024-03-19T11:00:00Z"
},
"action": "updated"
}
}💡 Use Case
Use this event to sync contacts with your CRM, trigger workflows when contact tags change, or maintain a backup copy of your contact database.
campaign.completed
Triggered when a campaign finishes sending all messages. The event includes comprehensive statistics about campaign performance.
{
"event": "campaign.completed",
"event_id": "evt_cmp_cmp_130",
"timestamp": "2024-03-19T14:30:00Z",
"channel_id": "ch_abc123",
"data": {
"campaign": {
"id": "cmp_spring_sale_2024",
"name": "Spring Sale 2024",
"status": "completed",
"started_at": "2024-03-19T10:00:00Z",
"completed_at": "2024-03-19T14:30:00Z",
"statistics": {
"total": 10000,
"sent": 10000,
"delivered": 9850,
"read": 8920,
"failed": 150,
"responses": 2150
}
}
}
}💡 Use Case
Use this event to send campaign performance reports to stakeholders, trigger follow-up campaigns based on results, or log campaign metrics in your analytics platform.