> ## Documentation Index
> Fetch the complete documentation index at: https://www.vobiz.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Vobiz Messaging API - Webhooks

> Create and manage Vobiz Messaging webhook (callback) subscriptions - choose the SMS, MMS, RCS and broadcast events to receive, sign deliveries with X-Webhook-Signature, and pause, update or delete subscriptions.

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](/docs/sms/webhooks).

## 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`](/docs/sms/api/webhooks/create-webhook) | Create a subscription for a URL and a set of events. |
| `GET` | [`/webhooks`](/docs/sms/api/webhooks/list-webhooks) | List your subscriptions, newest first. |
| `GET` | [`/webhooks/{id}`](/docs/sms/api/webhooks/get-webhook) | Retrieve one subscription. |
| `PUT` | [`/webhooks/{id}`](/docs/sms/api/webhooks/update-webhook) | Change the URL, secret, events or `active` flag. |
| `DELETE` | [`/webhooks/{id}`](/docs/sms/api/webhooks/delete-webhook) | 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

```bash cURL theme={null}
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"]
  }'
```

```json 201 Created theme={null}
{
  "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.

## Related

<CardGroup cols={2}>
  <Card title="Webhooks guide" icon="webhook" href="/docs/sms/webhooks">
    Payloads, signature verification and handler examples in Node and Python.
  </Card>

  <Card title="WebSocket" icon="bolt" href="/docs/sms/websocket">
    Live events for dashboards and consoles.
  </Card>

  <Card title="Broadcasts" icon="bullhorn" href="/docs/sms/broadcasts">
    Track bulk sends with `broadcast.updated`.
  </Card>

  <Card title="Conversations" icon="comments" href="/docs/sms/conversations">
    Thread inbound replies from `message.received`.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.