Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vobiz.ai/llms.txt

Use this file to discover all available pages before exploring further.

← Back to Webhooks

​
Event Payload Format

All webhook events share a consistent JSON structure with common fields and event-specific data. Events are delivered as HTTP POST requests with Content-Type: application/json.

​
Common Event Structure

All webhook events share these common fields:
FieldTypeDescription
eventstringThe event type (e.g., message.received)
event_idstringUnique identifier for this event (use for deduplication)
timestampstringISO 8601 timestamp when the event occurred
channel_idstringID of the WhatsApp channel this event relates to
dataobjectEvent-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.

​
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.

​
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.
Delivery does not guarantee the message was read, only that it reached the recipient’s device.

​
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).

​
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 will not receive read events even if they have read the message.

​
message.failed

Triggered when a message fails to send. The event includes error details explaining why delivery failed.

​
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 does not exist or has not been 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.

​
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.

​
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.