Skip to main content
POST
Create a webhook subscription
Two separate webhook systems work together in a Vobiz WhatsApp integration. See the Webhooks overview for the conceptual split. All endpoints are under the base URL https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp, except the inbound Meta callback which is at https://api.vobiz.ai/api/v1/webhooks/whatsapp.

Inbound (Meta → Vobiz)

These endpoints are called by Meta, not by your application. You normally configure the callback URL and verify token once inside your Meta App. The examples below are for understanding and local simulation only.

Verify webhook (challenge-response)

When you register the webhook in your Meta App, Meta sends a GET with the standard hub.* query params. Vobiz echoes the hub.challenge back as text/plain 200 only when hub.verify_token matches the token configured on the Vobiz side. No auth header is used on this endpoint.
Simulate Meta's verification
200 OK

Receive webhook (Meta callback)

Meta POSTs the WhatsApp Cloud API event here. Meta signs the request with X-Hub-Signature-256: sha256=<hex HMAC-SHA256 of the raw body, keyed by your Meta App Secret>. Vobiz verifies that signature and enforces a replay window, rejecting stale or future-dated payloads. The body is the standard Meta envelope (object = whatsapp_business_account, entry[].changes[].value carrying messaging_product, metadata, and any of contacts[], messages[], statuses[], calls[]).
Simulate a delivery status callback
200 OK
After Vobiz accepts an inbound Meta event, it fans it out to your registered subscriptions as an outbound webhook.

Outbound (Vobiz to your server)

Register an HTTPS endpoint and a shared secret. Vobiz then delivers a signed event envelope to your endpoint for the three supported event types. See the Event Reference for envelope and payload shapes, and the overview for signature verification. Authentication (subscription management): every request needs the X-Auth-ID: MA_XXXXXXXX and X-Auth-Token: YOUR_AUTH_TOKEN headers, and the {auth_id} in the path must be the account those credentials belong to. Get credentials from console.vobiz.ai.

Create webhook subscription

Register an HTTPS endpoint to receive events. Subscribing a URL you already have replaces its secret and reactivates it. A missing url or secret returns 400. Returns 201 Created; the secret isn’t returned.
cURL
201 Created

List webhook subscriptions

Returns the webhook subscriptions for your account, newest first. The secret is never included.
cURL
200 OK

Delete webhook subscription

Remove a subscription by its UUID. Vobiz stops delivering events to that URL. Returns 204 No Content, or 404 for an unknown subscription.
cURL
204 No Content

Delivery to your endpoint

When an event fires, Vobiz sends a POST to your registered url with: Headers Body - the common envelope (full reference):
The event_type values are message.inbound for a received message, message.status for a delivery status update (with status ∈ sent/delivered/read/failed), and call. followed by the WhatsApp call event (e.g. call.connect, call.terminate). The payload is the WhatsApp Business Platform webhook payload that triggered the event, unchanged. Vobiz waits up to 5 seconds for your endpoint to respond and delivers each event once. Return any 2xx status quickly, and do heavier processing after you respond.
Verify X-Webhook-Signature against the raw body before processing - compute HMAC-SHA256 with your secret, hex-encode, and constant-time compare. See the signature example.

Authorizations

X-Auth-ID
string
header
required

Your Vobiz account Auth ID (MA_XXXXXXXX).

X-Auth-Token
string
header
required

Your Vobiz account Auth Token.

Path Parameters

auth_id
string
required

Your account Auth ID. It must match the X-Auth-ID header.

Example:

"MA_XXXXXXXX"

Body

application/json
url
string<uri>
required

The HTTPS URL that receives event deliveries. Sending a URL you already subscribed updates its secret.

Example:

"https://example.com/webhooks/whatsapp"

secret
string
required

Shared secret used to sign deliveries (HMAC-SHA256, hex-encoded, in X-Webhook-Signature). Responses don't include it.

Example:

"YOUR_WEBHOOK_SECRET"

Response

The subscription. The secret is not returned.

id
string<uuid>
required

Subscription ID.

Example:

"6a1c3e5b-7d9f-4b2a-8c4e-6f8a0b2c4d16"

url
string<uri>
required
Example:

"https://example.com/webhooks/whatsapp"

status
string
required

Subscription state, for example active.

Example:

"active"

created_at
string<date-time>
required
Example:

"2026-10-20T09:15:00Z"

updated_at
string<date-time>
required
Example:

"2026-10-20T09:15:00Z"