WhatsApp Webhook Subscriptions API

openapi: 3.2.0
info:
  title: Meta Graph API - Application Connected Client Businesses…
  version: v23.0
  description: 'API for retrieving connected client businesses associated with a Meta application.


    This endpoint allows applications to retrieve information about businesses that have

    established client connections through the application. This is essential for managing

    business relationships and understanding client business configurations.'
  contact:
    name: Meta Business Platform Team
    url: https://developers.facebook.com/support
  license:
    name: Meta Platform Terms
    url: https://developers.facebook.com/terms
  termsOfService: https://developers.facebook.com/terms
servers:
- url: https://graph.facebook.com
  description: Production Graph API server
- url: https://graph.facebook.com
- url: https://graph.facebook.com
  description: WhatsApp Business Cloud API
- url: https://graph.facebook.com
  description: Meta Graph API production server
tags:
- name: Webhook Subscriptions
  description: APIs for managing WhatsApp Business Account webhook subscriptions
paths:
  /{Version}/{WABA-ID}/subscribed_apps:
    get:
      summary: Get All Subscriptions for a WABA
      description: 'Retrieve a list of all applications currently subscribed to webhook events

        for the specified WhatsApp Business Account.


        **Use Cases:**

        - Monitor which apps are subscribed to WABA webhook events

        - Audit subscription configurations and permissions

        - Verify subscription status before making changes

        - Retrieve subscription details for troubleshooting


        **Rate Limiting:**

        Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff.


        **Caching:**

        Subscription data can be cached for short periods, but may change when apps

        subscribe or unsubscribe. Implement appropriate cache invalidation strategies.'
      operationId: getAllSubscriptionsForAWaba
      tags:
      - Webhook Subscriptions
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - name: Version
        in: path
        required: true
        description: 'Graph API version to use for this request. Determines the API behavior and available features.

          '
        schema:
          type: string
          pattern: ^v[0-9]+\.[0-9]+$
        example: v23.0
      - name: WABA-ID
        in: path
        required: true
        description: 'WhatsApp Business Account ID. This ID can be found in your WhatsApp Manager

          or through business management APIs.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      - name: fields
        in: query
        required: false
        description: 'Comma-separated list of fields to include in the response. If not specified,

          default fields will be returned. Available fields: id, name, link

          '
        schema:
          type: string
        example: id,name,link
      responses:
        '200':
          description: Successfully retrieved list of subscribed applications
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscribedAppsResponse'
              examples:
                multiple_subscriptions:
                  summary: Multiple apps subscribed to WABA
                  value:
                    data:
                    - whatsapp_business_api_data:
                        id: '1234567890123456'
                        name: Business Messaging App
                        link: https://www.facebook.com/games/?app_id=1234567890123456
                    - whatsapp_business_api_data:
                        id: '2345678901234567'
                        name: Customer Support Bot
                        link: https://www.facebook.com/games/?app_id=2345678901234567
                no_subscriptions:
                  summary: No apps subscribed to WABA
                  value:
                    data: []
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: WABA-ID must be a valid numeric string'
                  type: OAuthException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '401':
          description: Unauthorized - Invalid or missing access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid OAuth access token
                  type: OAuthException
                  code: 190
                  error_subcode: 463
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '403':
          description: Forbidden - Insufficient permissions or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Your app doesn't have permission to access this WhatsApp Business Account
                  type: OAuthException
                  code: 200
                  error_subcode: 1349174
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  error_user_title: Permission Denied
                  error_user_msg: Your app doesn't have permission to access this resource
        '404':
          description: Not Found - WABA ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: WhatsApp Business Account not found
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '422':
          description: Unprocessable Entity - Request parameters are valid but cannot be processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: The requested fields are not available for this subscription
                  type: GraphMethodException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Application request limit reached
                  type: OAuthException
                  code: 4
                  error_subcode: 2446079
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
        '500':
          description: Internal Server Error - Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: An unexpected error occurred. Please retry your request
                  type: GraphMethodException
                  code: 2
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
      security:
      - bearerAuth: []
    post:
      summary: Subscribe to WABA Webhooks
      description: 'Subscribe your application to webhook events for the specified WhatsApp Business Account.

        This enables your app to receive real-time notifications for events such as message

        deliveries, status updates, and other WABA activities.


        **Use Cases:**

        - Enable webhook notifications for your app

        - Configure custom callback URLs for webhook delivery

        - Set up webhook verification tokens for security

        - Override default app webhook settings for specific WABAs


        **Rate Limiting:**

        Standard Graph API rate limits apply. Subscription operations may have additional

        throttling to prevent abuse.


        **Security:**

        Always use HTTPS endpoints for webhook callbacks. Verify webhook authenticity

        using the provided verification tokens and signature validation.'
      operationId: subscribeToWabaWebhooks
      tags:
      - Webhook Subscriptions
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - name: Version
        in: path
        required: true
        description: 'Graph API version to use for this request. Determines the API behavior and available features.

          '
        schema:
          type: string
          pattern: ^v[0-9]+\.[0-9]+$
        example: v23.0
      - name: WABA-ID
        in: path
        required: true
        description: 'WhatsApp Business Account ID. This ID can be found in your WhatsApp Manager

          or through business management APIs.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      requestBody:
        required: false
        description: Optional configuration for webhook subscription
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
            examples:
              basic_subscription:
                summary: Basic subscription without custom configuration
                value: {}
              custom_callback:
                summary: Subscription with custom callback URL
                value:
                  override_callback_uri: https://your-webhook-endpoint.com/webhook
                  verify_token: YOUR_VERIFY_TOKEN_PLACEHOLDER
      responses:
        '200':
          description: Successfully subscribed to WABA webhooks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                basic_subscription_success:
                  summary: Basic subscription successful
                  value:
                    success: true
                custom_callback_success:
                  summary: Custom callback subscription successful
                  value:
                    success: true
                    data:
                    - override_callback_uri: https://your-webhook-endpoint.com/webhook
                      whatsapp_business_api_data:
                        id: '1234567890123456'
                        name: Business Messaging App
                        link: https://www.facebook.com/games/?app_id=1234567890123456
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid callback URI format
                  type: OAuthException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '401':
          description: Unauthorized - Invalid or missing access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid OAuth access token
                  type: OAuthException
                  code: 190
                  error_subcode: 463
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '403':
          description: Forbidden - Insufficient permissions or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Your app doesn't have permission to subscribe to this WhatsApp Business Account
                  type: OAuthException
                  code: 200
                  error_subcode: 1349174
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  error_user_title: Permission Denied
                  error_user_msg: Your app doesn't have permission to access this resource
        '404':
          description: Not Found - WABA ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: WhatsApp Business Account not found
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '422':
          description: Unprocessable Entity - Request parameters are valid but cannot be processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Webhook callback URL is not reachable or invalid
                  type: GraphMethodException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Application request limit reached
                  type: OAuthException
                  code: 4
                  error_subcode: 2446079
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
        '500':
          description: Internal Server Error - Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: An unexpected error occurred. Please retry your request
                  type: GraphMethodException
                  code: 2
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
      security:
      - bearerAuth: []
    delete:
      summary: Unsubscribe from WABA Webhooks
      description: 'Unsubscribe your application from webhook events for the specified WhatsApp Business Account.

        This will stop your app from receiving webhook notifications for this WABA.


        **Use Cases:**

        - Disable webhook notifications when no longer needed

        - Clean up subscriptions during app decommissioning

        - Temporarily disable webhooks for maintenance

        - Remove subscriptions for WABAs no longer managed by your app


        **Rate Limiting:**

        Standard Graph API rate limits apply. Unsubscription operations are typically

        processed immediately.


        **Important:**

        Unsubscribing will immediately stop all webhook deliveries for this WABA.

        Ensure your application can handle the cessation of webhook events gracefully.'
      operationId: unsubscribeFromWabaWebhooks
      tags:
      - Webhook Subscriptions
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - name: Version
        in: path
        required: true
        description: 'Graph API version to use for this request. Determines the API behavior and available features.

          '
        schema:
          type: string
          pattern: ^v[0-9]+\.[0-9]+$
        example: v23.0
      - name: WABA-ID
        in: path
        required: true
        description: 'WhatsApp Business Account ID. This ID can be found in your WhatsApp Manager

          or through business management APIs.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      responses:
        '200':
          description: Successfully unsubscribed from WABA webhooks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                unsubscribe_success:
                  summary: Unsubscription successful
                  value:
                    success: true
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: WABA-ID must be a valid numeric string'
                  type: OAuthException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '401':
          description: Unauthorized - Invalid or missing access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid OAuth access token
                  type: OAuthException
                  code: 190
                  error_subcode: 463
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '403':
          description: Forbidden - Insufficient permissions or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Your app doesn't have permission to unsubscribe from this WhatsApp Business Account
                  type: OAuthException
                  code: 200
                  error_subcode: 1349174
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  error_user_title: Permission Denied
                  error_user_msg: Your app doesn't have permission to access this resource
        '404':
          description: Not Found - WABA ID does not exist or subscription not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: WhatsApp Business Account not found or not subscribed
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '422':
          description: Unprocessable Entity - Request parameters are valid but cannot be processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Cannot unsubscribe: subscription is required for active integrations'
                  type: GraphMethodException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Application request limit reached
                  type: OAuthException
                  code: 4
                  error_subcode: 2446079
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
        '500':
          description: Internal Server Error - Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: An unexpected error occurred. Please retry your request
                  type: GraphMethodException
                  code: 2
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
      security:
      - bearerAuth: []
components:
  schemas:
    SubscriptionRequest:
      type: object
      description: Request body for subscribing to WABA webhooks
      properties:
        override_callback_uri:
          type: string
          description: Custom webhook callback URL to override app default
          example: https://your-webhook-endpoint.com/webhook
        verify_token:
          type: string
          description: Verification token for webhook security
          example: YOUR_VERIFY_TOKEN_PLACEHOLDER
    GraphAPIError:
      type: object
      description: Standard Graph API error response
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          - type
          - code
          properties:
            message:
              type: string
              description: Human-readable error message
              example: Invalid parameter
            type:
              type: string
              description: Error category type
              example: OAuthException
            code:
              type: integer
              description: Numeric error code
              example: 100
            error_subcode:
              type: integer
              description: More specific error subcode when available
              example: 33
            fbtrace_id:
              type: string
              description: Unique identifier for debugging and support requests with Meta
              example: AXsgnV2Cm3ZMGF3dF_cfYIn
            is_transient:
              type: boolean
              description: Indicates whether this error is temporary and the request should be retried
              example: false
            error_user_title:
              type: string
              description: User-friendly error title for display purposes
              example: Permission Denied
            error_user_msg:
              type: string
              description: User-friendly error message for display purposes
              example: Your app doesn't have permission to access this resource
    SubscriptionResponse:
      type: object
      description: Response after successful subscription operation
      required:
      - success
      properties:
        success:
          type: boolean
          description: Indicates whether the subscription operation was successful
          example: true
        data:
          type: array
          description: Array containing subscription details
          items:
            $ref: '#/components/schemas/SubscribedApp'
    SubscribedApp:
      type: object
      description: Application subscribed to the WABA
      properties:
        id:
          type: string
          description: Application ID
          example: '9876543210987654'
        name:
          type: string
          description: Application name
          example: WhatsApp Integration App
    SubscribedAppsResponse:
      type: object
      description: Response containing list of subscribed applications
      required:
      - data
      properties:
        data:
          type: array
          description: Array of subscribed applications
          items:
            $ref: '#/components/schemas/SubscribedApp'
  parameters:
    Authorization:
      name: Authorization
      in: header
      description: 'Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.

        '
      required: true
      schema:
        type: string
        pattern: ^Bearer\s+[A-Za-z0-9\-_.]+.*$
        example: Bearer EAABwzLixnjYBOzYmNMJJGfHq9DgNh...
    UserAgent:
      name: User-Agent
      in: header
      description: The user agent string identifying the client software making the request.
      required: false
      schema:
        type: string
        default: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
        pattern: ^[a-zA-Z0-9\-_]+\/[0-9]+\.[0-9]+\.[0-9]+(;[a-zA-Z0-9\-=\.]+)?(\s+[a-zA-Z0-9\-_]+\/[0-9\-\.]+)?$
        example: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'System user access token with whatsapp_business_management permission. Format: Bearer YOUR_SYSTEM_USER_ACCESS_TOKEN

        '