---
title: "Set or remove the account's webhook"
method: PUT
path: "/v1/webhook"
---

# Set or remove the account's webhook

`PUT /v1/webhook`

## Request

- Base URL: `https://volai.cz`
- URL: `https://volai.cz/v1/webhook`
- Auth: HTTP bearer

Sets (or replaces) the target URL and the events you subscribe to. The response also includes the signing `secret` - save it right away, `GET` won't return it again later. An empty `events: []` means **subscribe to every event**, not none - including ones added later. If you only want some events, list them. Conversely, an empty `url: ""` **cancels** the webhook - volai then sends nothing, and the response returns `url: null`. How to verify the signature is covered on the [Webhooks](https://volai.cz/en/docs/webhooks).

## Request body

- object
  - `url` string, required: Public HTTPS callback URL. An empty string removes the webhook. Verify the signature using the secret returned by this request.
  - `events` string[]: Complete list of event names to subscribe to. Omit or send [] to subscribe to all events, including future additions. message.sent reports carrier acceptance, not delivery to the recipient. message.received delivers a message received on your SMS number.

## Response `200`

Webhook config

- object
  - `url` string, nullable, required
  - `events` string[], required
  - `secret` string

## Other responses

- `400`: Error codes: validation (request), invalid_url (request), invalid_events (request).
- `401`: Error codes: unauthorized (request).
- `403`: Error codes: account_suspended (account).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service).

---

[API](https://skmtc.dev/volai/apis/volai-rest-api.md) · [All operations](https://skmtc.dev/volai/apis/volai-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volai/apis/volai-rest-api/revisions/12029b05e2fa?raw)