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 the API for changes to objects that may or may not have happened, and helps you avoid reaching your rate limit.

This document gives a quick overview of Webhooks, how they work, and the information they contain as well as the differences between the WhatsApp Business Management and Cloud API Webhooks and the On-Premises API Webhooks.

Objects, Fields, and Values

An 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
  • 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 memssage 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 messageserrors, 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

Webhooks sent using the WhatsApp Business Management API or Cloud API 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.

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.

Related Post

Leave a Comment

Cookie Consent with Real Cookie Banner