Webhooks for the WhatsApp Business Platform

WhatsApp Business Blog

Using Node.js to implement webhooks

Webhooks allows you to receive real-time HTTP notifications of changes to specific objects. For example, we could send you a notification when a user sends you a message or when a message template's status has changed. This prevents you from having to query our APIs for changes to objects that may or may not have happened, and helps you avoid reaching your rate limit.

This document provides an overview of Webhooks and they apply to the WhatsApp Business Management API, WhatsApp Business Platform Cloud API, and WhatsApp Business Platform On-Premises API.

Objects, Fields, and Values

Each API can have multiple object types so whenever you configure a Webhook you must first choose an object type. Since different objects have different fields, you must then subscribe to specific fields for that object type. Whenever there's a change to the value of any object field you have subscribed to, you will receive a notification.

Notifications are sent to you as HTTP POST requests and contain a JSON payload that describes the change.

Available Webhooks

The following table outlines the information you can receive from Webhooks.

API	Objects
Cloud API	A customer performs an action such as replying to a business message A customer updates their phone number A message is sent by a business, delivered to the customer, or read by the customer, includes pricing information An error has occurred for a message
On-Premises API	A customer performs an action such as replying to a business message A customer updates their phone number A message is sent by a business, delivered to the customer, or read by the customer, includes pricing information An error has occurred for a message
WhatsApp Business Management API	Changes to official business account status and display name status The status change for a WhatsApp Business Account review A WhatsApp Business Account information has been updated, including information for policy violations The capabilities for a WhatsApp Business Account have been changed, such as a change in the number of conversations per phone number A message template has been approved, rejected, or disabled The display name associated with a phone number has been approved or rejected The quality related status for a phone number has changed

Example Text Message Notification

The following examples represent a Webhook notification sent to you when a user has sent you a text message.

Cloud API

For Cloud API, the object is always whatsapp_business_account but the field will be indicative of the type of information being sent.

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": PHONE_NUMBER,
          "phone_number_id": PHONE_NUMBER_ID
        },
        "contacts": [{
          "profile": {
            "name": "NAME"
          },
          "wa_id": PHONE_NUMBER
        }],
        "messages": [{
          "from": PHONE_NUMBER,
          "id": "wamid.ID",
          "timestamp": TIMESTAMP,
          "text": {
            "body": "MESSAGE_BODY"
          },
          "type": "text"
        }]
      },
      "field": "messages"
    }]
  }]
}

On-Premises API

For On-Premises API, because your client is sending the Webhook instead of Meta, the object will be contacts and messages, errors, or statuses and pricing.

{
  "contacts": [{
    "profile": {
      "name": "NAME"
    },
    "wa_id": "WHATSAPP_BUSINESS_ACCOUNT_ID"
  }],
  "messages":[{
    "from": "PHONE_NUMBER",
    "id": "wamid.ID",
    "timestamp": "TIMESTAMP",
    "text": {
      "body": "MESSAGE_BODY"
    },
    "type": "text"
  }]
}

HTTPS Server

All webhooks are sent using HTTPS, so your server must be able to receive and process HTTPS requests, and it must have a valid TLS/SSL certificate installed. Self-signed certificates are not supported.

Learn More

Learn more about Webhooks for a specific API.

Next Steps

Get Started - Determine which APIs is right for your business.
Display Name – Set up the business name displayed in WhatsApp messages.
Phone Numbers - Associate a phone number with your WhatsApp Business Account
Pricing - Learn about pricing and how to set up payments.

WhatsApp Business Platform | Cloud API | On-Premises API | Business Management API