> ## 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. # 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`. ## OpenAPI ````yaml openapi-sms.yaml POST /webhooks openapi: 3.0.3 info: title: Vobiz Messaging API description: > Send and receive SMS, MMS and RCS messages, buy messaging numbers, register for US 10DLC and toll-free, run broadcasts, manage conversations, opt-outs and webhooks. **Base URL:** `https://api.vobiz.ai/api/v1/sms` **Authentication:** every request needs the `X-Auth-ID` and `X-Auth-Token` headers. The account is taken from your credentials; you never put an account ID in a path or body. Field names in this API are camelCase. version: '1.0' contact: email: support@vobiz.ai url: https://vobiz.ai servers: - url: https://api.vobiz.ai/api/v1/sms description: Production security: - AuthID: [] AuthToken: [] tags: - name: Messages description: Send messages and inspect their delivery state. - name: Numbers description: >- Messaging-capable numbers on your account, inventory search, purchase and release. - name: Coverage description: Where you can send, per country. - name: Conversations description: Two-way threads between one of your numbers and a contact. - name: Opt-outs description: Numbers that must not receive messages on a channel. - name: Webhooks description: Subscriptions that deliver message and broadcast events to your server. - name: Broadcasts description: Bulk sends from an uploaded recipient list. - name: RCS Senders description: RCS sender (agent) identities and their message templates. - name: 10DLC Brands description: US 10DLC brand registration. - name: 10DLC Campaigns description: US 10DLC campaigns, toll-free verification and supporting documents. paths: /webhooks: post: tags: - Webhooks summary: Create a webhook description: >- 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`. Every delivery carries `X-Webhook-ID`, `X-Webhook-Event` and `X-Webhook-Signature`, a lower-case hex HMAC-SHA256 of the raw body keyed with your `secret`. The subscription is active as soon as it is created; see the Webhooks guide for the payload envelope and a verification example. operationId: create-webhook requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWebhookRequest' example: url: https://example.com/vobiz/webhooks secret: YOUR_WEBHOOK_SECRET events: - message.received - message.delivered - message.failed responses: '201': description: The subscription, active immediately. content: application/json: schema: $ref: '#/components/schemas/WebhookSubscription' example: 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' '400': description: '`url` is missing or the body is not valid JSON.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: url: value: error: url is required body: value: error: invalid request body '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/ServerError' x-codeSamples: - lang: typescript label: Node SDK source: > import { VobizClient } from "@vobiz/sdk"; const client = new VobizClient({ apiKey: "MA_XXXXXXXX", authToken: "YOUR_AUTH_TOKEN" }); await client.sms.webhooks.createWebhook({ url: "https://example.com/vobiz/webhooks", secret: "YOUR_WEBHOOK_SECRET", events: ["message.received", "message.delivered", "message.failed"] }) - lang: python label: Python SDK source: | 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" ], ) - lang: go label: Go SDK source: | import ( "context" vobiz "github.com/vobiz-ai/Vobiz-Go-SDK" "github.com/vobiz-ai/Vobiz-Go-SDK/client" "github.com/vobiz-ai/Vobiz-Go-SDK/option" "github.com/vobiz-ai/Vobiz-Go-SDK/sms" ) c := client.NewClient( option.WithAPIKey("MA_XXXXXXXX"), option.WithAuthToken("YOUR_AUTH_TOKEN"), ) request := &sms.CreateWebhookRequest{ URL: "https://example.com/vobiz/webhooks", Secret: vobiz.String( "YOUR_WEBHOOK_SECRET", ), Events: []sms.WebhookEvent{ sms.WebhookEventMessageReceived, sms.WebhookEventMessageDelivered, sms.WebhookEventMessageFailed, }, } c.Sms.Webhooks.CreateWebhook( context.TODO(), request, ) - lang: java label: Java SDK source: | import com.vobiz.api.VobizApiClient; VobizApiClient client = VobizApiClient .builder() .apiKey("MA_XXXXXXXX") .authToken("YOUR_AUTH_TOKEN") .build(); client.sms().webhooks().createWebhook( CreateWebhookRequest .builder() .url("https://example.com/vobiz/webhooks") .secret("YOUR_WEBHOOK_SECRET") .events( Optional.of( Arrays.asList(WebhookEvent.MESSAGE_RECEIVED, WebhookEvent.MESSAGE_DELIVERED, WebhookEvent.MESSAGE_FAILED) ) ) .build() ); - lang: ruby label: Ruby SDK source: > require 'vobiz' client = Vobiz::Client.new(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: %w[message.received message.delivered message.failed] ) - lang: csharp label: C# SDK source: | using Vobiz; using Vobiz.Sms; var client = new VobizApiClient("YOUR_AUTH_TOKEN", "MA_XXXXXXXX"); await client.Sms.Webhooks.CreateWebhookAsync( new CreateWebhookRequest { Url = "https://example.com/vobiz/webhooks", Secret = "YOUR_WEBHOOK_SECRET", Events = new List() { WebhookEvent.MessageReceived, WebhookEvent.MessageDelivered, WebhookEvent.MessageFailed, }, } ); - lang: php label: PHP SDK source: > sms->webhooks->createWebhook( new CreateWebhookRequest([ 'url' => 'https://example.com/vobiz/webhooks', 'secret' => 'YOUR_WEBHOOK_SECRET', 'events' => [ WebhookEvent::MessageReceived->value, WebhookEvent::MessageDelivered->value, WebhookEvent::MessageFailed->value, ], ]), ); components: schemas: CreateWebhookRequest: type: object required: - url properties: url: type: string format: uri description: >- 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`. example: https://example.com/vobiz/webhooks secret: type: string description: >- 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. example: YOUR_WEBHOOK_SECRET events: type: array description: >- 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. default: - message.received - message.delivered - message.failed items: $ref: '#/components/schemas/WebhookEvent' description: The subscription to create. Only `url` is required. WebhookSubscription: type: object properties: id: type: string format: uuid example: 8d4f2a6b-3e1c-4b9a-a7d2-5c8e1f0b6a93 description: >- Unique identifier of the subscription (UUID). Use it with `GET`, `PUT` and `DELETE /webhooks/{id}`. accountId: type: string example: MA_XXXXXXXX description: >- Auth ID of the account that owns the subscription, for example `MA_XXXXXXXX`. url: type: string format: uri example: https://example.com/vobiz/webhooks description: The URL that receives `POST` deliveries. secret: type: string description: >- The signing secret for `X-Webhook-Signature`, returned in clear. Keep it out of logs and client-side code. example: YOUR_WEBHOOK_SECRET events: type: array items: $ref: '#/components/schemas/WebhookEvent' example: - message.received - message.delivered - message.failed description: >- Event names delivered to this URL. An event is delivered only when its name appears here exactly. active: type: boolean example: true description: >- `true` when deliveries are on. New subscriptions start `true`; set it with `PUT /webhooks/{id}`. createdAt: type: string format: date-time example: '2026-10-18T07:22:11Z' description: >- When the subscription was created (ISO 8601). Read it from `GET /webhooks/{id}` or `GET /webhooks`. description: >- A webhook subscription: the URL Vobiz delivers your chosen events to, and the secret used to sign them. Error: type: object description: >- The body of every error response: a flat object with one `error` string that explains what went wrong. Use the HTTP status code to decide how to handle the error, and log `error` for diagnosis. required: - error properties: error: type: string example: 'recipient has opted out: +14155550123' description: >- Human-readable explanation of the error, for example `phoneNumber is required` or `recipient has opted out: +14155550123`. Branch on the HTTP status code rather than on this text. WebhookEvent: type: string description: >- 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). enum: - message.status - message.delivered - message.failed - message.received - broadcast.updated responses: Unauthorized: description: Missing or invalid `X-Auth-ID` / `X-Auth-Token`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: missing or invalid credentials ServerError: description: Unexpected error. Retry with the same idempotency key where one applies. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: internal error securitySchemes: AuthID: type: apiKey in: header name: X-Auth-ID description: Your Vobiz account Auth ID (`MA_XXXXXXXX`). AuthToken: type: apiKey in: header name: X-Auth-Token description: Your Vobiz account Auth Token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.