Create a webhook
Registers an HTTPS endpoint that receives the events you subscribe to as signed POST requests. Only url is required; omit events to subscribe to message.received, message.delivered and message.failed.
curl --request POST \
--url https://api.vobiz.ai/api/v1/sms/webhooks \
--header 'Content-Type: application/json' \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"url": "https://example.com/vobiz/webhooks"
}
'from vobiz import Vobiz
client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN")
client.sms.webhooks.create_webhook(
url="https://example.com/vobiz/webhooks",
secret="YOUR_WEBHOOK_SECRET",
events=[
"message.received",
"message.delivered",
"message.failed"
],
)
const options = {
method: 'POST',
headers: {
'X-Auth-ID': '<api-key>',
'X-Auth-Token': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({url: 'https://example.com/vobiz/webhooks'})
};
fetch('https://api.vobiz.ai/api/v1/sms/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "8d4f2a6b-3e1c-4b9a-a7d2-5c8e1f0b6a93",
"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"
}Authorizations
Your Vobiz account Auth ID (MA_XXXXXXXX).
Your Vobiz account Auth Token.
Body
The subscription to create. Only url is required.
The HTTPS URL that receives POST deliveries, for example https://example.com/vobiz/webhooks. Required; an empty or missing value returns 400 with url is required.
"https://example.com/vobiz/webhooks"
Shared secret used to compute X-Webhook-Signature on every delivery. Choose a long random value and store it on your server; if you omit it the subscription is created with an empty secret.
"YOUR_WEBHOOK_SECRET"
Event names to deliver to this URL, matched exactly. Defaults to message.received, message.delivered and message.failed when you omit it or send an empty array.
A messaging event name you can subscribe to: message.status (delivery state changed), message.delivered (reached the handset), message.failed (could not be delivered), message.received (inbound message) or broadcast.updated (broadcast status or counters changed).
message.status, message.delivered, message.failed, message.received, broadcast.updated Response
The subscription, active immediately.
A webhook subscription: the URL Vobiz delivers your chosen events to, and the secret used to sign them.
Unique identifier of the subscription (UUID). Use it with GET, PUT and DELETE /webhooks/{id}.
"8d4f2a6b-3e1c-4b9a-a7d2-5c8e1f0b6a93"
Auth ID of the account that owns the subscription, for example MA_XXXXXXXX.
"MA_XXXXXXXX"
The URL that receives POST deliveries.
"https://example.com/vobiz/webhooks"
The signing secret for X-Webhook-Signature, returned in clear. Keep it out of logs and client-side code.
"YOUR_WEBHOOK_SECRET"
Event names delivered to this URL. An event is delivered only when its name appears here exactly.
A messaging event name you can subscribe to: message.status (delivery state changed), message.delivered (reached the handset), message.failed (could not be delivered), message.received (inbound message) or broadcast.updated (broadcast status or counters changed).
message.status, message.delivered, message.failed, message.received, broadcast.updated [
"message.received",
"message.delivered",
"message.failed"
]
true when deliveries are on. New subscriptions start true; set it with PUT /webhooks/{id}.
true
When the subscription was created (ISO 8601). Read it from GET /webhooks/{id} or GET /webhooks.
"2026-10-18T07:22:11Z"
Was this page helpful?
curl --request POST \
--url https://api.vobiz.ai/api/v1/sms/webhooks \
--header 'Content-Type: application/json' \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"url": "https://example.com/vobiz/webhooks"
}
'from vobiz import Vobiz
client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN")
client.sms.webhooks.create_webhook(
url="https://example.com/vobiz/webhooks",
secret="YOUR_WEBHOOK_SECRET",
events=[
"message.received",
"message.delivered",
"message.failed"
],
)
const options = {
method: 'POST',
headers: {
'X-Auth-ID': '<api-key>',
'X-Auth-Token': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({url: 'https://example.com/vobiz/webhooks'})
};
fetch('https://api.vobiz.ai/api/v1/sms/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "8d4f2a6b-3e1c-4b9a-a7d2-5c8e1f0b6a93",
"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"
}