> ## Documentation Index > Fetch the complete documentation index at: https://docs.minimo.it/llms.txt > Use this file to discover all available pages before exploring further. # Register Webhook > Register the URL of your bot that receives WhatsApp events Minimo sends the [events](https://docs.minimo.it/api-reference/whatsapp-transport/webhooks.md) you subscribe to to this URL, signed with your `secret`. > [!WARNING] > > While an active webhook subscribes to `whatsapp.message.received`, **every WhatsApp number of your workspace is > answered by your bot**: Minimo's own AI assistant stops replying on them. See [One responder per > number](https://docs.minimo.it/api-reference/whatsapp-transport/overview.md#one-responder-per-number). ## Use Cases * **Connect your bot**: subscribe to `whatsapp.message.received` and answer with [Send a Message](https://docs.minimo.it/api-reference/whatsapp-transport/send.md) * **Know what was delivered**: add `whatsapp.message.status` to learn when a message is delivered, read or failed ## The secret `secret` is required (at least 16 characters). Minimo signs every delivery with it (`X-Minimo-Signature`) and never returns it: `hasSecret` only tells you one is set. Store it when you register; to change it, use [Update Webhook](https://docs.minimo.it/api-reference/whatsapp-transport/webhook-update.md). See [Verify the signature](https://docs.minimo.it/api-reference/whatsapp-transport/webhooks.md#verify-the-signature). ## Permissions The API key needs the **WhatsApp** permission. ## OpenAPI ````yaml post /public/v1/webhooks/registrations openapi: 3.1.0 info: title: API Documentation description: Documentation for transactional and subscribe APIs version: 1.0.0 servers: - url: https://app.minimo.it security: - bearerAuth: [] paths: /public/v1/webhooks/registrations: servers: - url: https://api.minimo.it post: summary: Register a webhook description: >- Register the URL that receives WhatsApp events. While an active webhook subscribes to `whatsapp.message.received`, every WhatsApp number of the workspace is answered by your bot: Minimo's own AI assistant does not reply on them. operationId: createWebhookRegistration requestBody: required: true content: application/json: schema: type: object required: - name - url - secret - events properties: name: type: string minLength: 1 description: A label for you. url: type: string description: Your HTTPS endpoint that receives the events. secret: type: string minLength: 16 description: >- Used to sign every delivery (`X-Minimo-Signature`). Never returned: store it. events: type: array minItems: 1 items: type: string enum: - whatsapp.message.received - whatsapp.message.status description: >- `whatsapp.message.received` = a contact wrote to you. `whatsapp.message.status` = a message you sent was sent, delivered, read or failed. method: type: string enum: - POST - GET default: POST headers: type: array description: >- Static headers to send on every delivery, for example an auth header for your endpoint. items: type: object required: - key - value properties: key: type: string value: type: string example: name: Support bot url: https://bot.example.com/minimo/webhook secret: a-long-random-shared-secret-32chars events: - whatsapp.message.received - whatsapp.message.status responses: '201': description: The new webhook content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/WebhookRegistration' example: data: id: 42 name: Support bot url: https://bot.example.com/minimo/webhook events: - whatsapp.message.received - whatsapp.message.status status: active method: POST headers: {} hasSecret: true created: '2026-11-13T10:00:00.000Z' '400': description: A field missing, of the wrong type or out of range. content: application/json: schema: type: object properties: status: type: string example: FAIL message: type: string '401': description: >- Missing or invalid API key, or a key without the `WhatsApp` permission. security: - bearerAuth: [] x-codeSamples: - label: CLI lang: cURL source: |- curl --request POST \ --url 'https://api.minimo.it/public/v1/webhooks/registrations' \ --header 'Authorization: Bearer {{BEARER_TOKEN}}' \ --header 'Content-Type: application/json' \ --data '{"name": "Support bot", "url": "https://bot.example.com/minimo/webhook", "secret": "a-long-random-shared-secret-32chars", "events": ["whatsapp.message.received", "whatsapp.message.status"]}' - lang: JavaScript source: >- const res = await fetch('https://api.minimo.it/public/v1/webhooks/registrations', { method: 'POST', headers: { 'Authorization': 'Bearer {{BEARER_TOKEN}}', 'Content-Type': 'application/json', }, body: JSON.stringify({"name": "Support bot", "url": "https://bot.example.com/minimo/webhook", "secret": "a-long-random-shared-secret-32chars", "events": ["whatsapp.message.received", "whatsapp.message.status"]}), }); const { data } = await res.json(); console.log(data); - lang: Python source: |- import requests res = requests.post( 'https://api.minimo.it/public/v1/webhooks/registrations', headers={'Authorization': 'Bearer {{BEARER_TOKEN}}'}, json={'name': 'Support bot', 'url': 'https://bot.example.com/minimo/webhook', 'secret': 'a-long-random-shared-secret-32chars', 'events': ['whatsapp.message.received', 'whatsapp.message.status']}, ) print(res.json()) components: schemas: WebhookRegistration: type: object description: >- A webhook registration. The `secret` is never returned: `hasSecret` tells you one is set. properties: id: type: integer example: 42 name: type: string example: Support bot url: type: string example: https://bot.example.com/minimo/webhook events: type: array items: type: string enum: - whatsapp.message.received - whatsapp.message.status status: type: string enum: - active - inactive method: type: string enum: - POST - GET headers: type: object additionalProperties: type: string description: >- Static headers sent on every delivery, as `{ "Header-Name": "value" }`. hasSecret: type: boolean created: type: string format: date-time securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: mn-API_CLIENT_ID-API_KEY ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.