Vobiz Messaging API - Webhooks

Webhooks (callbacks) deliver messaging events to a URL on your server as signed POST requests. A webhook subscription is the record that says which URL receives which events and which secret signs them. You use these endpoints to create subscriptions, change their events or URL, pause them and delete them. For the delivery payloads and a verification example, see the Webhooks guide.

The webhook subscription object

Field	Type	Meaning
`id`	string (UUID)	Unique identifier of the subscription.
`accountId`	string	Auth ID of the account that owns it, for example `MA_XXXXXXXX`.
`url`	string	The URL that receives `POST` deliveries.
`secret`	string	The signing secret for `X-Webhook-Signature`, returned in clear.
`events`	string[]	Event names delivered to `url`.
`active`	boolean	`true` when deliveries are on.
`createdAt`	string	When the subscription was created (ISO 8601).

The response includes secret, so keep subscription responses out of logs and client-side code.

Endpoints

Method	Endpoint	What it does
`POST`	`/webhooks`	Create a subscription for a URL and a set of events.
`GET`	`/webhooks`	List your subscriptions, newest first.
`GET`	`/webhooks/{id}`	Retrieve one subscription.
`PUT`	`/webhooks/{id}`	Change the URL, secret, events or `active` flag.
`DELETE`	`/webhooks/{id}`	Delete a subscription and stop its deliveries.

Events

Event	When it fires
`message.status`	The delivery state of a message you sent changed.
`message.delivered`	A message you sent reached the handset.
`message.failed`	A message you sent could not be delivered.
`message.received`	A contact sent a message to one of your numbers or RCS senders.
`broadcast.updated`	A broadcast changed status or its counters moved.

When you omit events or send an empty array, the subscription receives message.received, message.delivered and message.failed. An event reaches a subscription only when the subscription is active and its events list contains that exact name.

Create a subscription

cURL

curl -X POST "https://api.vobiz.ai/api/v1/sms/webhooks" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/vobiz/webhooks",
    "secret": "YOUR_WEBHOOK_SECRET",
    "events": ["message.received", "message.delivered", "message.failed"]
  }'

201 Created

{
  "id": "9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01",
  "accountId": "MA_XXXXXXXX",
  "url": "https://example.com/vobiz/webhooks",
  "secret": "YOUR_WEBHOOK_SECRET",
  "events": ["message.received", "message.delivered", "message.failed"],
  "active": true,
  "createdAt": "2026-10-18T07:22:11Z"
}

Only url is required; a missing or empty url returns 400 with url is required. New subscriptions are active immediately.

Update, pause and delete

Partial updates. PUT /webhooks/{id} changes only the fields you send. A field you send replaces the current value, and events replaces the whole list.
Pause. Send {"active": false} to stop deliveries and keep the subscription. Send {"active": true} to resume.
Rotate the secret. Send a new secret and update your verifier at the same time; deliveries are signed with the new value from that point.
Read back. PUT and DELETE return 200 with {"status":"ok"}. Call GET /webhooks/{id} to see the updated subscription.
Empty list. GET /webhooks returns a bare JSON array, and null when you have no subscriptions. Treat null as an empty list.

Delivery headers

Every delivery is a POST with a JSON body of the form {"event", "timestamp", "data"} and these headers.

Header	Value
`X-Webhook-ID`	A UUID for the event. It stays the same across redeliveries; de-duplicate on it.
`X-Webhook-Event`	The event name, for example `message.delivered`.
`X-Webhook-Signature`	Lower-case hex HMAC-SHA256 of the raw request body, keyed with the subscription `secret`. No prefix.

Return a 2xx status quickly. Any other response is treated as a failure, and the event is redelivered until your endpoint accepts it.

Webhooks guide

Payloads, signature verification and handler examples in Node and Python.

WebSocket

Live events for dashboards and consoles.

Broadcasts

Track bulk sends with broadcast.updated.

Conversations

Thread inbound replies from message.received.

Getting Started

API Reference

Guides

Vobiz Messaging API - Webhooks

The webhook subscription object

Endpoints

Events

Create a subscription

Update, pause and delete

Delivery headers

Webhooks guide

WebSocket

Broadcasts

Conversations

​The webhook subscription object

​Endpoints

​Events

​Create a subscription

​Update, pause and delete

​Delivery headers

​Related

Webhooks guide

WebSocket

Broadcasts

Conversations

The webhook subscription object

Endpoints

Events

Create a subscription

Update, pause and delete

Delivery headers

Related