WhatsApp Webhooks
Receive real-time notifications about WhatsApp events directly to your application. Webhooks enable you to build powerful integrations and automated workflows based on customer interactions.
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
Event Occurs
A customer sends a message, a message is delivered, or any other tracked event happens
Vobiz Sends Request
Vobiz immediately makes an HTTP POST request to your configured webhook URL with event data
Your Server Processes
Your application receives the webhook, validates it, and processes the event data
Send Response
Your server responds with HTTP 200 to acknowledge receipt
Common Use Cases
Webhooks enable countless automation and integration possibilities:
Real-time Notifications
Get instant alerts when customers send messages, enabling fast response times.
Examples:
- ✓Notify support team of new inquiries
- ✓Alert sales team of hot leads
- ✓Trigger automated workflows
Message Status Tracking
Track delivery and read status of messages in your own systems.
Examples:
- ✓Update CRM with delivery confirmations
- ✓Log read receipts for compliance
- ✓Monitor campaign performance in real-time
System Integration
Sync WhatsApp conversations with your existing tools and platforms.
Examples:
- ✓Create tickets in helpdesk software
- ✓Add contacts to marketing automation
- ✓Log conversations in customer database
Compliance & Auditing
Maintain complete records of all customer communications.
Examples:
- ✓Archive messages for regulatory compliance
- ✓Track opt-in/opt-out events
- ✓Monitor agent performance
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
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-Signatureheader - 3. Your server computes its own signature using the same secret key
- 4. If signatures match, the webhook is authentic; otherwise, reject it
⚠️ Critical Security Requirement
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.
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 →