> ## 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.

# Update Webhook

> Change the URL, events or secret, or pause and resume delivery

Only the fields you send change.

## Use Cases

* **Pause delivery**: `{ "status": "inactive" }`, resume with `{ "status": "active" }`
* **Rotate the secret**: `{ "secret": "<new secret, at least 16 characters>" }`
* **Move your bot**: `{ "url": "https://new-host.example.com/minimo/webhook" }`

> [!NOTE]
>
> When no active webhook for `whatsapp.message.received` is left (paused, or the event removed), your WhatsApp numbers
> go back to the inbox: nobody answers automatically until you turn the AI assistant on again in Minimo or reactivate
> the webhook.

## Permissions

The API key needs the **WhatsApp** permission.


## OpenAPI

````yaml put /public/v1/webhooks/registrations/{id}
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/{id}:
    servers:
      - url: https://api.minimo.it
    put:
      summary: Update a webhook
      description: >-
        Change only the fields you send. Use `status` to pause or resume
        delivery. 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: updateWebhookRegistration
      parameters:
        - name: id
          in: path
          required: true
          description: The webhook `id` from Register Webhook or List Webhooks.
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              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: A new signing secret (rotation).
                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: Replaces the static headers.
                  items:
                    type: object
                    required:
                      - key
                      - value
                    properties:
                      key:
                        type: string
                      value:
                        type: string
                status:
                  type: string
                  enum:
                    - active
                    - inactive
                  description: >-
                    Pause (`inactive`) or resume (`active`) delivery without
                    deleting the webhook.
            example:
              status: inactive
      responses:
        '200':
          description: The updated 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: inactive
                  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.
        '404':
          description: No webhook with this id in your workspace.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: FAIL
                  message:
                    type: string
      security:
        - bearerAuth: []
      x-codeSamples:
        - label: CLI
          lang: cURL
          source: |-
            curl --request PUT \
              --url 'https://api.minimo.it/public/v1/webhooks/registrations/42' \
              --header 'Authorization: Bearer {{BEARER_TOKEN}}' \
              --header 'Content-Type: application/json' \
              --data '{"status": "inactive"}'
        - lang: JavaScript
          source: >-
            const res = await
            fetch('https://api.minimo.it/public/v1/webhooks/registrations/42', {
              method: 'PUT',
              headers: {
                'Authorization': 'Bearer {{BEARER_TOKEN}}',
                'Content-Type': 'application/json',
              },
              body: JSON.stringify({"status": "inactive"}),
            });

            const { data } = await res.json();

            console.log(data);
        - lang: Python
          source: |-
            import requests

            res = requests.put(
                'https://api.minimo.it/public/v1/webhooks/registrations/42',
                headers={'Authorization': 'Bearer {{BEARER_TOKEN}}'},
                json={'status': 'inactive'},
            )
            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.