> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wavix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a WhatsApp webhook

> Updates the URL of a WhatsApp webhook or turns it off or on, and returns the updated webhook.

Move events to a new URL without deleting the webhook, so its ID and signing secret stay the same, or pause events while your server is down for maintenance.

**Behavior:** Returns `200` with the updated webhook. With `enabled` set to `false`, Wavix cancels the deliveries still waiting. Events that Wavix records while the webhook is disabled aren't sent later; read them with [List WhatsApp events](https://docs.wavix.com/api-reference/whatsapp/list-whatsapp-events). With `enabled` set to `true`, the webhook gets the events that occur from then on.

**Requires:** Your account must have the WhatsApp channel enabled, must have a subscription plan, and must not be blocked or suspended.



## OpenAPI

````yaml https://wavix.github.io/wavix-openapi/wavix-api.yaml patch /v1/whatsapp/webhooks/{uuid}
openapi: 3.1.0
info:
  title: Wavix APIs
  description: >-
    Wavix provides robust APIs that let you integrate voice and text messaging
    features directly into your app. Send text, place calls, and access detailed
    reports  programmatically.
  termsOfService: https://wavix.com/terms-and-conditions
  license:
    name: MIT
    identifier: MIT
  contact:
    name: Wavix
    url: https://wavix.com
    email: support@wavix.com
  version: 2.0.0
servers:
  - url: https://api.wavix.com
    description: https://api.wavix.com
    variables: {}
security:
  - bearerAuth: []
tags:
  - name: SIP trunks
    description: SIP trunks
  - name: Buy
    description: Numbers
  - name: Cart
    description: Numbers
  - name: My numbers
    description: Numbers
  - name: Billing
    description: Billing, transactions, and invoices
  - name: Profile
    description: Account profile and customer information
  - name: CDRs
    description: Call detail records and call history
  - name: Speech Analytics
    description: Call transcription and speech analytics
  - name: SMS and MMS
    description: Messaging
  - name: Number Validator
    description: Phone number validation
  - name: Link shortener
    description: Short link and click metrics
  - name: 2FA
    description: Two-factor authentication
  - name: 10DLC
    description: 10DLC Campaigns and Brands
  - name: API Keys
    description: API key management
  - name: Call webhooks
    description: Webhook configuration for call events
  - name: Call control
    description: Programmable Voice
  - name: Call streaming
    description: Real-time call audio streaming over WebSocket
  - name: Call recording
    description: Call recording
  - name: Sub-accounts
    description: Sub-account management
  - name: Voice campaigns
    description: Outbound voice campaigns
  - name: Wavix Embeddable
    description: WebRTC embeddable widget
  - name: WhatsApp
    description: WhatsApp senders, templates, messages, webhooks, and events
  - name: WhatsApp webhook payloads
    description: >-
      Message, template, sender, and marketing preference events Wavix posts to
      your WhatsApp webhooks
paths:
  /v1/whatsapp/webhooks/{uuid}:
    patch:
      tags:
        - WhatsApp
      summary: Update a WhatsApp webhook
      description: >-
        Updates the URL of a WhatsApp webhook or turns it off or on, and returns
        the updated webhook.


        Move events to a new URL without deleting the webhook, so its ID and
        signing secret stay the same, or pause events while your server is down
        for maintenance.


        **Behavior:** Returns `200` with the updated webhook. With `enabled` set
        to `false`, Wavix cancels the deliveries still waiting. Events that
        Wavix records while the webhook is disabled aren't sent later; read them
        with [List WhatsApp
        events](https://docs.wavix.com/api-reference/whatsapp/list-whatsapp-events).
        With `enabled` set to `true`, the webhook gets the events that occur
        from then on.


        **Requires:** Your account must have the WhatsApp channel enabled, must
        have a subscription plan, and must not be blocked or suspended.
      operationId: whatsapp_webhooks_update
      parameters:
        - name: uuid
          in: path
          required: true
          description: >-
            ID of the webhook, as returned in `uuid` when you create the webhook
            or list your webhooks.
          schema:
            type: string
            format: uuid
          example: 6f1c2a4e-8b3d-4c5e-9f70-1a2b3c4d5e6f
      requestBody:
        description: Attributes of the webhook to change.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhatsAppWebhookUpdateRequest'
            examples:
              new-url:
                summary: Move events to a new URL
                value:
                  url: https://example.com/wavix/v2
              disable:
                summary: Stop sending events
                value:
                  enabled: false
        required: true
      responses:
        '200':
          description: The updated WhatsApp webhook. It never includes the signing secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsAppWebhookResponse'
              examples:
                default:
                  summary: The webhook after a new URL
                  value:
                    webhook:
                      uuid: 6f1c2a4e-8b3d-4c5e-9f70-1a2b3c4d5e6f
                      url: https://example.com/wavix/v2
                      group: messages
                      enabled: true
                      enabled_events:
                        - whatsapp.message.received
                        - whatsapp.message.sent
                        - whatsapp.message.delivered
                        - whatsapp.message.read
                        - whatsapp.message.failed
                        - whatsapp.contact.marketing_stopped
                        - whatsapp.contact.marketing_resumed
                      created_at: '2026-10-21T12:00:00Z'
        '400':
          description: >-
            The body is invalid. The JSON is malformed or empty, has no fields,
            or a field is unknown or `null`. The `detail` field says which.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/WhatsAppProblem'
              examples:
                invalid-request:
                  summary: The body has an unknown field
                  value:
                    type: https://docs.wavix.com/errors/invalid-request
                    title: Invalid Request
                    status: 400
                    detail: 'The request body has an unknown field: "group".'
                    instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                    error_class: permanent
                    error_code: INVALID_REQUEST
        '401':
          $ref: '#/components/responses/WhatsAppUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/WhatsAppForbiddenResponse'
        '404':
          description: >-
            No webhook with this ID belongs to your account, or WhatsApp isn't
            available for your account or isn't enabled yet.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/WhatsAppProblem'
              examples:
                webhook-not-found:
                  summary: No webhook matches the given uuid
                  value:
                    type: https://docs.wavix.com/errors/webhook-not-found
                    title: Webhook Not Found
                    status: 404
                    detail: Webhook Not Found
                    instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                    error_class: permanent
                    error_code: WEBHOOK_NOT_FOUND
        '413':
          description: The request body is over 16 KiB.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/WhatsAppProblem'
              examples:
                payload-too-large:
                  summary: The request body exceeds the size limit
                  value:
                    type: https://docs.wavix.com/errors/payload-too-large
                    title: Payload Too Large
                    status: 413
                    detail: The request body is too large.
                    instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                    error_class: permanent
                    error_code: PAYLOAD_TOO_LARGE
        '422':
          description: >-
            `url` isn't an `https` URL without credentials, is longer than 2,048
            bytes, or has a host with no address, or resolves to an address that
            isn't public or that Wavix doesn't allow. The `detail` field says
            which.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/WhatsAppProblem'
              examples:
                invalid-webhook-url:
                  summary: The URL isn't a public https URL
                  value:
                    type: https://docs.wavix.com/errors/invalid-webhook-url
                    title: Invalid Webhook URL
                    status: 422
                    detail: >-
                      The URL host resolves to an address that is not public or
                      that Wavix does not allow.
                    instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                    error_class: permanent
                    error_code: INVALID_WEBHOOK_URL
        '500':
          $ref: '#/components/responses/WhatsAppInternalServerErrorResponse'
        '503':
          description: >-
            The service is temporarily unavailable, or the lookup of the host of
            `url` failed. The request may be retried.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/WhatsAppProblem'
              examples:
                service-unavailable:
                  value:
                    type: https://docs.wavix.com/errors/service-unavailable
                    title: Service Unavailable
                    status: 503
                    detail: The service is temporarily unavailable.
                    instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                    error_class: retriable
                    error_code: SERVICE_UNAVAILABLE
                webhook-url-unverified:
                  summary: Wavix couldn't resolve the host of the URL
                  value:
                    type: https://docs.wavix.com/errors/webhook-url-unverified
                    title: Webhook URL Unverified
                    status: 503
                    detail: Webhook URL Unverified
                    instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                    error_class: retriable
                    error_code: WEBHOOK_URL_UNVERIFIED
      deprecated: false
      security:
        - bearerAuth:
            - whatsapp:write
components:
  schemas:
    WhatsAppWebhookUpdateRequest:
      title: WhatsAppWebhookUpdateRequest
      description: >-
        Fields to update on a WhatsApp webhook. Consumed by [Update a WhatsApp
        webhook](https://docs.wavix.com/api-reference/whatsapp/update-a-whatsapp-webhook).
        Specify at least one field; fields you omit keep their values.
      type: object
      additionalProperties: false
      minProperties: 1
      required: []
      properties:
        url:
          type: string
          format: uri
          maxLength: 2048
          description: >-
            New https URL that Wavix sends events to. Wavix checks it the same
            way as when you create a webhook.
          example: https://example.com/wavix/v2
        enabled:
          type: boolean
          description: >-
            Whether Wavix sends events to the webhook. When `false`, Wavix sends
            only test events. Read the others with [List WhatsApp
            events](https://docs.wavix.com/api-reference/whatsapp/list-whatsapp-events).
          example: false
    WhatsAppWebhookResponse:
      title: WhatsAppWebhookResponse
      description: >-
        A single WhatsApp webhook, returned when you create or retrieve a
        webhook.
      required:
        - webhook
      type: object
      additionalProperties: false
      properties:
        webhook:
          $ref: '#/components/schemas/WhatsAppWebhook'
    WhatsAppProblem:
      title: WhatsAppProblem
      description: >-
        An RFC 9457 problem document that describes an error from the WhatsApp
        API. Returned with the `application/problem+json` content type.
      required:
        - type
        - title
        - status
        - detail
        - instance
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          description: URI that identifies the problem type.
          example: https://docs.wavix.com/errors/whatsapp-not-available
        title:
          type: string
          description: Short, human-readable summary of the problem type.
          example: WhatsApp Not Available
        status:
          type: integer
          format: int32
          description: HTTP status code of the response.
          example: 404
        detail:
          type: string
          description: Human-readable explanation of this occurrence of the problem.
          example: WhatsApp is not available for this account.
        instance:
          type: string
          description: Request ID of this occurrence of the problem.
          example: 3a525ca2-6909-4c72-9399-905adf7f3a74
        error_class:
          type: string
          description: >-
            Machine-readable classification of the error. Possible values:


            - `permanent` — The request can't succeed as sent. Retrying doesn't
            help.

            - `retriable` — The failure is temporary. Retrying can succeed.

            - `rate_limited` — The request was rate limited. Retry later.

            - `invalid_template` — The template content is invalid.
          enum:
            - permanent
            - retriable
            - rate_limited
            - invalid_template
          example: permanent
        error_code:
          type: string
          description: >-
            Stable machine-readable error code. It's the problem type slug in
            upper case, with underscores in place of hyphens.
          example: WHATSAPP_NOT_AVAILABLE
        service_window_closed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Time the 24-hour service window of the recipient closed. Returned
            with `service-window-closed`. It's `null` when the recipient never
            wrote to the sender or the last message is older than the retained
            history.
          example: '2026-01-14T09:15:00.000Z'
    WhatsAppWebhook:
      title: WhatsAppWebhook
      description: >-
        A WhatsApp webhook of your account, returned when you create, list, or
        retrieve a webhook.
      type: object
      additionalProperties: false
      required:
        - uuid
        - url
        - group
        - enabled
        - enabled_events
        - created_at
      properties:
        uuid:
          type: string
          format: uuid
          description: Webhook ID. Test events carry it as `data.webhook_id`.
          example: 6f1c2a4e-8b3d-4c5e-9f70-1a2b3c4d5e6f
        url:
          type: string
          format: uri
          maxLength: 2048
          description: The https URL that Wavix sends events to.
          example: https://example.com/wavix
        group:
          $ref: '#/components/schemas/WhatsAppWebhookGroup'
        enabled:
          type: boolean
          description: >-
            Whether the webhook gets events. A disabled webhook gets only test
            events. Change it with [Update a WhatsApp
            webhook](https://docs.wavix.com/api-reference/whatsapp/update-a-whatsapp-webhook).
          example: true
        enabled_events:
          type: array
          readOnly: true
          description: >-
            Event types Wavix sends to the webhook, which are every event type
            of its `group`. When Wavix adds an event type to the group, the list
            includes it.
          items:
            $ref: '#/components/schemas/WhatsAppEventType'
          example:
            - whatsapp.message.received
            - whatsapp.message.sent
            - whatsapp.message.delivered
            - whatsapp.message.read
            - whatsapp.message.failed
            - whatsapp.contact.marketing_stopped
            - whatsapp.contact.marketing_resumed
        created_at:
          type: string
          format: date-time
          description: Date and time when the webhook was created, in ISO 8601 UTC.
          example: '2026-10-21T12:00:00Z'
        secret:
          type: string
          pattern: ^whsec_[A-Za-z0-9+/]{43}=$
          description: >-
            The signing secret, in the Standard Webhooks format. Returned only
            when you create the webhook; store it, because it's never returned
            again.
          example: whsec_AQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyA=
    WhatsAppWebhookGroup:
      title: WhatsAppWebhookGroup
      description: >-
        Group of WhatsApp event types that a webhook receives. Your account can
        have one webhook per group. Possible values:


        - `messages` — Messages your senders receive, the delivery outcome of
        messages you send, and contacts' marketing preferences.

        - `templates` — Changes to the status, category, and quality rating of
        your templates.

        - `senders` — Changes to the status and quality rating of your senders.
      type: string
      enum:
        - messages
        - templates
        - senders
      example: messages
    WhatsAppEventType:
      title: WhatsAppEventType
      description: >-
        Type of a WhatsApp event. Each type belongs to one webhook group. Wavix
        can add event types to a group, so ignore an event whose `type` you
        don't recognize. Possible values:


        - `whatsapp.message.received` — One of your senders received a message.

        - `whatsapp.message.sent` — A message you sent has the `sent` status: it
        isn't delivered yet.

        - `whatsapp.message.delivered` — A message you sent was delivered to the
        recipient. WhatsApp can skip it when the recipient reads the message
        right away.

        - `whatsapp.message.read` — The recipient opened a message you sent.
        WhatsApp reports it only when the recipient has read receipts turned on.

        - `whatsapp.message.failed` — A message you sent wasn't delivered.
        `data.error` says why.

        - `whatsapp.contact.marketing_stopped` — A contact asked to stop
        marketing messages from one of your senders. Meta doesn't deliver
        marketing templates to the contact until they resume them.

        - `whatsapp.contact.marketing_resumed` — A contact asked to receive
        marketing messages from one of your senders again.

        - `whatsapp.template.approved` — The provider approved one of your
        templates, so you can send it.

        - `whatsapp.template.rejected` — The provider rejected one of your
        templates.

        - `whatsapp.template.paused` — The provider paused one of your
        templates.

        - `whatsapp.template.disabled` — One of your templates is disabled and
        can't be sent.

        - `whatsapp.template.flagged` — Meta flagged one of your templates
        because of negative feedback. It can still be sent, but it's at risk of
        being paused or disabled.

        - `whatsapp.template.category_changed` — Meta moved one of your
        templates to another category, which changes the rate of each message
        sent with it.

        - `whatsapp.template.quality_changed` — Meta changed the quality rating
        of one of your templates.

        - `whatsapp.template.updated` — The status of one of your templates
        changed to a value that has no event type of its own, such as `pending`,
        `in_appeal`, or `deleted`.

        - `whatsapp.sender.connected` — One of your senders can send messages
        within its messaging limit, for example after registration or when a
        restriction ends.

        - `whatsapp.sender.restricted` — One of your senders reached its
        messaging limit. It can't start new conversations until the 24-hour
        window resets, but it can still reply to customers who messaged it.

        - `whatsapp.sender.flagged` — The quality rating of one of your senders
        dropped to low. The status returns to `connected` if the rating returns
        to medium or high within 7 days.

        - `whatsapp.sender.banned` — The provider banned one of your senders.

        - `whatsapp.sender.disconnected` — One of your senders is disconnected
        from the provider.

        - `whatsapp.sender.quality_changed` — Meta changed the quality rating of
        one of your senders.

        - `whatsapp.sender.updated` — The status of one of your senders changed
        to a value that has no event type of its own, such as `pending`,
        `migrated`, or `deleted`.
      type: string
      enum:
        - whatsapp.message.received
        - whatsapp.message.sent
        - whatsapp.message.delivered
        - whatsapp.message.read
        - whatsapp.message.failed
        - whatsapp.contact.marketing_stopped
        - whatsapp.contact.marketing_resumed
        - whatsapp.template.approved
        - whatsapp.template.rejected
        - whatsapp.template.paused
        - whatsapp.template.disabled
        - whatsapp.template.flagged
        - whatsapp.template.category_changed
        - whatsapp.template.quality_changed
        - whatsapp.template.updated
        - whatsapp.sender.connected
        - whatsapp.sender.restricted
        - whatsapp.sender.flagged
        - whatsapp.sender.banned
        - whatsapp.sender.disconnected
        - whatsapp.sender.quality_changed
        - whatsapp.sender.updated
      example: whatsapp.message.received
  responses:
    WhatsAppUnauthorizedResponse:
      description: >-
        Authentication failed or wasn't provided, or the account is suspended,
        blocked, or has no subscription plan.
      headers: {}
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/WhatsAppProblem'
          examples:
            authentication-required:
              summary: The API key or token is missing or isn't valid
              value:
                type: https://docs.wavix.com/errors/authentication-required
                title: Authentication Required
                status: 401
                detail: Authentication is required to access this resource.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: permanent
                error_code: AUTHENTICATION_REQUIRED
            account-suspended:
              summary: The account is suspended
              value:
                type: https://docs.wavix.com/errors/authentication-required
                title: Authentication Required
                status: 401
                detail: The account is suspended.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: permanent
                error_code: AUTHENTICATION_REQUIRED
            account-blocked:
              summary: The account is blocked
              value:
                type: https://docs.wavix.com/errors/authentication-required
                title: Authentication Required
                status: 401
                detail: The account is blocked.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: permanent
                error_code: AUTHENTICATION_REQUIRED
            account-without-plan:
              summary: The account has no subscription plan
              value:
                type: https://docs.wavix.com/errors/authentication-required
                title: Authentication Required
                status: 401
                detail: The account has no subscription plan.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: permanent
                error_code: AUTHENTICATION_REQUIRED
    WhatsAppForbiddenResponse:
      description: >-
        Returns when the API key doesn't have the scope the operation needs, or
        the request isn't allowed for the account's region.
      headers: {}
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/WhatsAppProblem'
          examples:
            access-denied:
              value:
                type: https://docs.wavix.com/errors/access-denied
                title: Access Denied
                status: 403
                detail: The API key has no access to this resource.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: permanent
                error_code: ACCESS_DENIED
    WhatsAppInternalServerErrorResponse:
      description: >-
        Returns when an unexpected error occurs on the server; the request may
        be retried.
      headers: {}
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/WhatsAppProblem'
          examples:
            internal-error:
              value:
                type: https://docs.wavix.com/errors/internal-error
                title: Internal Error
                status: 500
                detail: Internal Error
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: retriable
                error_code: INTERNAL_ERROR
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Wavix API key. Pass as `Authorization: Bearer <api_key>`. Keys support
        per-resource scopes (none / read / write). See [Restricted keys and
        scopes](https://docs.wavix.com/api-reference/authentication#restricted-keys-and-scopes).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.