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.