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.

Two separate webhook systems work together in a Vobiz WhatsApp integration.
SystemDirectionPurpose
Meta WebhooksMeta → VobizMessage received, delivery status, read receipts. Vobiz registers these with Meta on your behalf.
Vobiz SubscriptionsVobiz → Your serverVobiz forwards normalized event payloads to your endpoint URL.

​
Meta webhooks

These endpoints are called by Meta, not by your application. Use the examples below to test and simulate Meta’s behavior during development.

​
Verify webhook (challenge-response)

GET https://api.vobiz.ai/v1/webhooks/whatsapp
When you register a webhook in Meta Business Manager, Meta sends a GET request with a hub.challenge parameter. Vobiz responds with the challenge value to confirm ownership. No authentication required on this endpoint.
ParamDescription
hub.modeAlways subscribe
hub.verify_tokenThe token you set in Meta Business Manager
hub.challengeRandom string Meta expects back in the response
Simulate Meta's verification
curl -X GET \
  "https://api.vobiz.ai/v1/webhooks/whatsapp?hub.mode=subscribe&hub.verify_token=whatsapp-verify-token&hub.challenge=test_challenge_123"
200 OK
test_challenge_123

​
Receive webhook (Meta callback)

POST https://api.vobiz.ai/v1/webhooks/whatsapp
Meta sends this POST whenever an event occurs. Vobiz validates the X-Hub-Signature-256 header before processing.
Simulate a delivery status update
curl -X POST \
  "https://api.vobiz.ai/v1/webhooks/whatsapp" \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: sha256={webhook_signature}" \
  -d '{"object":"whatsapp_business_account","entry":[{"id":"{waba_id}","changes":[{"value":{"messaging_product":"whatsapp","statuses":[{"id":"wamid.test","status":"delivered","timestamp":"1711111111","recipient_id":"919876543210"}]},"field":"messages"}]}]}'

​
Vobiz webhook subscriptions

Configure Vobiz to push event notifications to your server. Register your endpoint URL and a shared secret. Authentication: X-Auth-ID, X-Auth-Token, Accept: application/json

​
Create webhook subscription

POST https://api.vobiz.ai/v1/messaging/webhooks
Register a new webhook endpoint. Vobiz sends a verification request to your URL immediately after creation to confirm it is reachable.
FieldRequiredDescription
urlYesHTTPS endpoint to receive events
secretYesShared secret for HMAC-SHA256 signature verification
cURL
curl -X POST \
  "https://api.vobiz.ai/v1/messaging/webhooks" \
  -H "X-Auth-ID: {auth_id}" \
  -H "X-Auth-Token: {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.com/webhooks/whatsapp","secret":"your-shared-secret"}'
201 Created
{"id":"wh_sub_abc123","url":"https://your-server.com/webhooks/whatsapp","status":"active","created_at":"2026-03-25T10:00:00Z"}

​
List webhook subscriptions

GET https://api.vobiz.ai/v1/messaging/webhooks
Returns all active webhook subscriptions for your account.
cURL
curl -X GET \
  "https://api.vobiz.ai/v1/messaging/webhooks" \
  -H "X-Auth-ID: {auth_id}" \
  -H "X-Auth-Token: {auth_token}"

​
Delete webhook subscription

DELETE https://api.vobiz.ai/v1/messaging/webhooks/{webhook_id}
Remove a webhook subscription. Vobiz stops sending events to that URL immediately.
cURL
curl -X DELETE \
  "https://api.vobiz.ai/v1/messaging/webhooks/{webhook_id}" \
  -H "X-Auth-ID: {auth_id}" \
  -H "X-Auth-Token: {auth_token}"
204 No Content
// Empty body on success