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

# Webhook Subscribe

> Route inbound messages on this number to a webhook. Drops any connected agent.

Sets the number's default routing to `webhook` and assigns `defaultWebhook` to the
given webhook. Any agent previously connected to the number is dropped — call
[`POST /phone-numbers/{number}/connect-agent/`](/api-reference/phone-numbers/connect-agent)
to put one back.

When `applyToExisting` is `true`, every existing conversation on this number is
updated so the new routing takes effect for in-flight chats: `activeAgent` is
cleared and any open session is dropped. Phone-number routing changes do **not**
fire `subscription.activated` / `subscription.revoked` webhook events — those
are reserved for the per-conversation
[subscribe](/api-reference/conversations/subscribe) /
[unsubscribe](/api-reference/conversations/unsubscribe) endpoints.

<Note>
  Webhooks themselves must be created in the [dashboard](https://wassist.app/developers/webhooks).
  There is no API for webhook creation.
</Note>

Sandbox numbers (shared system numbers with no WhatsApp Business Account)
scope the change to the requesting user's own conversation; the shared
defaults are not touched and `applyToExisting` is ignored.


## OpenAPI

````yaml api-reference/openapi.json POST /api/v1/phone-numbers/{number}/subscribe/
openapi: 3.0.3
info:
  title: Wassist API
  version: 1.0.0
  description: API for building WhatsApp AI agents
servers:
  - url: https://alpha-plagiocephalic-darrell.ngrok-free.dev
    description: Development
security: []
tags:
  - name: Agents
    description: Create and manage AI agents
  - name: Conversations
    description: Chat conversations and messages
  - name: WhatsApp
    description: WhatsApp Business account management
  - name: Contacts
    description: Contact management
  - name: Integrations
    description: Third-party integrations
paths:
  /api/v1/phone-numbers/{number}/subscribe/:
    post:
      tags:
        - api
      description: Route this number to a webhook.
      operationId: api_v1_phone_numbers_subscribe_create
      parameters:
        - in: path
          name: number
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneNumber'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumber'
          description: ''
      security:
        - ApiKeyAuth: []
components:
  schemas:
    PhoneNumber:
      type: object
      description: Serializer for WhatsappNumber model.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        number:
          type: string
          maxLength: 15
        whatsappPhoneNumberId:
          type: string
        whatsappBusinessAccount:
          type: string
          readOnly: true
        activeAgent:
          type: string
          readOnly: true
        defaultRouting:
          type: string
          readOnly: true
        defaultWebhook:
          type: string
          readOnly: true
        isSandbox:
          type: boolean
          readOnly: true
      required:
        - activeAgent
        - defaultRouting
        - defaultWebhook
        - id
        - isSandbox
        - number
        - whatsappBusinessAccount
        - whatsappPhoneNumberId
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication. Pass your API key in the X-API-Key header.

````