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.

​
Why Use Webhooks?

Instead of constantly polling the API to check for new messages or status updates, webhooks push data to your application the instant events occur, providing:
  • Real-time updates - Instant event delivery.
  • Efficiency - No polling required.
  • Scalability - Handle high volumes.

​
What are Webhooks?

A webhook is an HTTP callback that sends data to your application when specific events occur in Vobiz. When an event happens (like receiving a message), Vobiz makes a POST request to your webhook URL with the event details.

​
How Webhooks Work

  1. Event occurs - A customer sends a message, a message is delivered, or any other tracked event happens.
  2. Vobiz sends request - Vobiz immediately makes an HTTP POST request to your configured webhook URL with event data.
  3. Your server processes - Your application receives the webhook, validates it, and processes the event data.
  4. Send response - Your server responds with HTTP 200 to acknowledge receipt.

​
Common use cases

Webhooks enable countless automation and integration possibilities:
  • CRM sync - Automatically create contacts and log conversations in your CRM when customers message you.
  • Helpdesk integration - Open support tickets in Zendesk, Freshdesk, or Intercom when customers reach out.
  • Chatbot automation - Trigger AI-powered responses or route conversations to human agents based on intent.
  • Analytics dashboards - Stream message events into your data warehouse for real-time reporting.
  • Order fulfillment - Update order status systems when delivery confirmations arrive.

​
Event Types

Vobiz sends webhooks for various WhatsApp events. You can subscribe to specific events or all of them:
  • message.received - Triggered when your business receives a message from a customer.
  • message.sent - Triggered when a message is successfully sent from your business.
  • message.delivered - Triggered when a sent message is delivered to the recipient’s device.
  • message.read - Triggered when a recipient reads your message (blue checkmarks).
  • message.failed - Triggered when a message fails to send, with error details.
  • contact.updated - Triggered when contact information is created or updated.
  • campaign.completed - Triggered when a campaign finishes sending all messages.
View Complete Event Reference →

​
Security

Webhooks can be a security risk if not properly validated. Vobiz implements industry-standard security measures to ensure webhook authenticity:

​
HMAC Signature Verification

Every webhook request includes an X-Vobiz-Signature header containing an HMAC-SHA256 signature. This signature is generated using your webhook secret key. How it works:
  1. Vobiz generates an HMAC signature of the request body using your secret key.
  2. The signature is sent in the X-Vobiz-Signature header.
  3. Your server computes its own signature using the same secret key.
  4. If signatures match, the webhook is authentic; otherwise, reject it.
Always verify the webhook signature before processing any webhook data. Failing to do so could allow malicious actors to send fake events to your application.

​
Additional Security Measures

  • HTTPS only - Webhook URLs must use HTTPS to encrypt data in transit. HTTP URLs are not supported.
  • IP whitelisting - Optionally restrict webhook requests to Vobiz IP addresses for an additional layer of security.
  • Retry mechanism - If your server is temporarily down, Vobiz retries webhook delivery with exponential backoff for up to 24 hours.
  • Secret key rotation - You can rotate your webhook secret key at any time from the console for enhanced security.
View Webhook Events →

​
Best Practices

  • Respond quickly - Return HTTP 200 within 5 seconds of receiving a webhook. Process time-consuming tasks asynchronously using a job queue to avoid timeouts.
  • Handle duplicates - Webhooks may occasionally be delivered more than once. Use the event ID to detect and ignore duplicate events in your processing logic.
  • Monitor webhook health - Check the webhook delivery logs in the Vobiz Console regularly. Failed deliveries indicate issues with your endpoint that need attention.
  • Use event filtering - Only subscribe to events you actually need. This reduces webhook volume and processing overhead.
  • Don’t block the response - Never perform long-running operations (API calls, database writes, email sending) in the webhook handler. Queue these tasks and respond immediately.
  • Don’t trust without verification - Always validate the HMAC signature before processing webhook data. Never assume a request to your webhook URL is legitimate without verification.

​
Ready to Set Up Webhooks?

Follow our step-by-step guide to configure webhooks in the Vobiz Console and start receiving real-time events. View Webhook Events →

​
Next Steps