WhatsApp Notification Subscriptions

System Webhooks are triggered when an event occurs on a WABA or a phone number. You can now subscribe to these webhooks to get notifications for changes to your WhatsApp Business Account settings. There are many notification types, such as account updates, changes to message templates, phone number updates, and when you have received a message from a customer.

These notifications can be received in one of two ways:

  • Through Webhooks - receive notifications through a custom webhook URL
  • Via Slack - receive notifications in a designated channel within your Slack workspace.

To create a subscription, you can send a request to the Create a Subscription endpoint of the Channel Manager API.

Create a WhatsApp Notification Subscription With Webhooks

To receive updates via webhook, you must first create a custom webhook URL that is configured to accept

POST
requests; take a look at our Webhooks guide if you are unsure how to do so. You can then send a request to the subscriptions endpoint with the following parameters to create the subscription:

{
    "type": "webhook",
    "whatsapp_subscribe_types": "account_alerts,account_update",
    "vonage_subscribe_types": "vonage_number_onboarded",
    "webhook": {
      "url": "https://example.com/webhook"
    }
}

Here:

  • url should contain your custom webhook URL.
  • whatsapp_subscribe_types is an optional parameter where you can list specific WhatsApp notification types that you want to receive through your subscription. If this is not included, the subscription will include all of the subscription types.
  • vonage_subscribe_types is an optional parameter where you can list specific Vonage notification types that you want to receive through your subscription. If this is not included, the subscription will include all of the subscription types.

You can find a full code example in the Create a WhatsApp Notification Subscription With Webhooks code snippet.

Example Webhooks

This example shows a template status update; as indicated in the event field, the template has been rejected:

{
    "notification_id": "id",
    "timestamp": "2023-02-21T15:34:39Z",
    "channel": "whatsapp",
    "whatsapp": {
        "waba_info": {
            "waba_id": "<WABA_ID>",
            "solution_id": "<WABA_SOLUTION_ID>", // if present
            "api_key": "<WABA_API_KEY>"
        },
        "notification_type": "message_template_status_update",
        "notification_value": {
            "event": "REJECTED",
            "message_template_id": "<TEMPLATE_ID>",
            "message_template_name": "<TEMPLATE_NAME>",
            "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>",
            "reason": "<REJECTION_REASON>"
        }
    }
}

In this example, the webhook indicates an account update where a phone number has been added:

{
    "notification_id": "id",
    "timestamp": "2023-02-21T15:34:39Z",
    "channel": "whatsapp",
    "whatsapp": {
        "waba_info": {
            "waba_id": "<WABA_ID>",
            "solution_id": "<WABA_SOLUTION_ID>", // if present
            "api_key": "<WABA_API_KEY>"
        },
        "whatsapp_number_info": {
            "phone_number": "<PHONE_NUMBER>",
            "api_key": "<NUMBER_API_KEY>"
        },
        "notification_type": "account_update",
        "notification_value": {
            "phone_number": "<PHONE_NUMBER>",
            "event": "PHONE_NUMBER_ADDED"
        }
    }
}

Create a WhatsApp Notification Subscription for Slack

To receive notifications via Slack, you can send a request to the subscriptions endpoint with the following parameters:

{
    "type": "slack",
    "whatsapp_subscribe_types": "account_alerts,account_update,message_template_status_update",
    "slack": {
      "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
    }
}

Here:

  • The url field should contain an incoming webhook URL created for your Slack workspace. Please refer to the Slack webhook documentation for more information on how to configure this URL.
  • whatsapp_subscribe_types is an optional parameter where you can list specific notification types that you want to receive through your subscription. If this is not included, the subscription will include all of the subscription types.

You can find a full code example in the Create a WhatsApp Notification Subscription for Slack code snippet.

Example Notification

Once your subscription is created, you'll begin to receive updates in the specified Slack channel, for example:

An example Slack notification showing a WhatsApp account update

Notification Types

  • There are many potential values for whatsapp_subscribe_types, shown in both the webhook and Slack notifications. You can see the full list of notification types and their descriptions in the Meta WhatsApp documentation.
  • There is currently only one value possible for vonage_subscribe_types, which is vonage_number_onboarded.

List All Subscriptions

To list all of your existing subscriptions, send a

GET
request to the subscriptions endpoint; code samples can be found in the List Existing Notification Subscriptions code snippet.

Delete a Subscription

To delete a subscription, send a

DELETE
request with the unique ID of the subscription you want to delete. Code samples can be found in the Delete a Subscription code snippet.

Further Reading