Webhooks API

Two separate webhook systems work together in a Vobiz WhatsApp integration.

Overview

Meta Webhooks

Callbacks from Meta's Cloud API to Vobiz — message received, delivery status, read receipts. Vobiz registers these with Meta on your behalf.

Vobiz Webhook Subscriptions

Callbacks from Vobiz to your server — Vobiz forwards normalized event payloads to your endpoint URL.

Meta Webhooks

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

Verify Webhook (Challenge-Response)

GEThttps://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.

hub.mode	Always `subscribe`
hub.verify_token	The token you set in Meta Business Manager
hub.challenge	Random string Meta expects back in the response

cURL — 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"

Response — 200 OK

test_challenge_123

Receive Webhook (Meta Callback)

POSThttps://api.vobiz.ai/v1/webhooks/whatsapp

Meta sends this POST whenever an event occurs. Vobiz validates the X-Hub-Signature-256 header before processing.

cURL — 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.

Create Webhook Subscription

POSThttps://api.vobiz.ai/v1/messaging/webhooks

Register a new webhook endpoint. Vobiz will send a verification request to your URL immediately after creation to confirm it is reachable.

Field	Required	Description
url	Required	HTTPS endpoint to receive events
secret	Required	Shared secret for HMAC-SHA256 signature verification

Authentication Required:

• X-Auth-ID: Your Account Auth ID
• X-Auth-Token: Your Account Auth Token
• Accept: application/json

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"}'

Response — 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

GEThttps://api.vobiz.ai/v1/messaging/webhooks

Returns all active webhook subscriptions for your account.

Authentication Required:

• X-Auth-ID: Your Account Auth ID
• X-Auth-Token: Your Account Auth Token
• Accept: application/json

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

DELETEhttps://api.vobiz.ai/v1/messaging/webhooks/{webhook_id}

Remove a webhook subscription. Vobiz will stop sending events to that URL immediately.

Authentication Required:

• X-Auth-ID: Your Account Auth ID
• X-Auth-Token: Your Account Auth Token
• Accept: application/json

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}"

Response — 204 No Content

// Empty body on success

Calls API

Webhooks Overview

Last updated: April 2026Edit this page