Webhooks

Webhooks are user-defined HTTP callbacks that are triggered by specific events. Whenever that trigger event occurs, the WhatsApp Business API client sees the event, collects the data, and immediately sends a notification (HTTPs request) to the Webhook URL configured in the Webhooks setup step.

For the purposes of this use case, your Webhooks server must be reachable from Meta and have HTTPs support and a valid SSL certificate. See Webhooks, Getting Started for requirements on creating a Webhooks endpoint and configuring the Webhooks product.

To get Webhooks notifications, your application must subscribe to the WABA you want to receive alerts for. See Webhooks for WhatsApp Business Accounts for a full guide.

Understanding Webhooks

All Webhooks have the following generic format:

{
  "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"
              },
              # specific Webhooks payload            
          },
          "field": "messages"
        }
      ]
    }
  ]
}

See Components for information on each field.

If you receive a message that is not supported for the Cloud API beta release, you will get an unknown message webhook.

Examples

Received Text Messages

The following is an example of a text message you received from a customer:

{
  "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": "WHATSAPP_ID"
                }
              ],
              "messages": [
                {
                  "from": "PHONE_NUMBER",
                  "id": "wamid.ID",
                  "timestamp": "TIMESTAMP",
                  "text": {
                    "body": "MESSAGE_BODY"
                  },
                  "type": "text"
                }
              ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

The following is an example of a text message you receive from a customer, when you have the show_security_notifications parameter set to true in the application settings.

{
  "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": "WHATSAPP_ID"
	            }
		    ],
               "messages": [
		       {
                    "from": "PHONE_NUMBER",
                    "id": "ID",
                    "identity": {
                        "acknowledged": true,
                        "created_timestamp": TIMESTAMP,
                        "hash": "HASH"
                    },
                    "text": {
                        "body": "MESSAGE_BODY"
                    },
                    "timestamp": "TIMESTAMP",
                    "type": "text"
                }
              ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Received Media Messages

When a message with media is received, the WhatsApp Business API downloads the media. A notification is sent to your Webhook once the media is downloaded.

The Webhook notification contains information that identifies the media object and enables you to find and retrieve the object. Use the media endpoints to retrieve the media.

{
  "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": "WHATSAPP_ID"
                }
              ],
              "messages": [
                {
                  "from": "PHONE_NUMBER",
                  "id": "wamid.ID",
                  "timestamp": "TIMESTAMP",
                  "type": "image",
                  "image": {
                    "caption": "CAPTION",
                    "mime_type": "image/jpeg",
                    "sha256": "IMAGE_HASH",
                    "id": "ID"
                  }
                }
              ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Received Unknown Messages

It’s possible to receive an unknown message callback notification. The following is an example of a message you received from a customer that is not supported.

{
  "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": "WHATSAPP_ID"
                }
               ],
              "messages": [
                {
                  "from": "PHONE_NUMBER",
                  "id": "wamid.ID", 
                  "timestamp": "TIMESTAMP",
                  "errors": [ 
                    { 
                      "code": 131051, 
                      "details": "Message type is not currently supported",
                      "title": "Unsupported message type"
                    }
                   ],
                   "type": "unknown"
                   }
                 ]
            }
            "field": "messages"
        }
       ],
    }
  ]
}

Received User Changed Number Notification

When a user changes their phone number on WhatsApp, you receive a system message notification:

{
  "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"
              },
              "messages": [
                {
                  "from": "PHONE_NUMBER",
                  "id": "wamid.ID",
                  "system": {
                    "body": "NAME changed from PHONE_NUMBER to PHONE_NUMBER",
                    "new_wa_id": "NEW_PHONE_NUMBER",
                    "type": "user_changed_number"
                  },
                  "timestamp": "TIMESTAMP",
                  "type": "system"
                }
              ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Message Status Update Notifications

The WhatsApp Business API sends notifications to inform you of the status of the messages between you and users. When a message is sent successfully, you receive a notification when the message is sent, delivered, and read. The order of these notifications in your app may not reflect the actual timing of the message status. View the timestamp to determine the timing, if necessary.

The following is an example of message status update Webhooks:

{
  "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"
              },
              "statuses": [
                {
                  "id": "wamid.ID",
                  "status": "sent",
                  "timestamp": "TIMESTAMP",
                  "recipient_id": "PHONE_NUMBER"
                }
              ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Sample Webhook with failed status:

{
  "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"
              },
              "statuses": [
                {
                  "id": "wamid.ID",
                  "status": "failed",
                  "timestamp": "TIMESTAMP",
                  "recipient_id": "PHONE_NUMBER",
                  "errors": [
                    {
                      "code": 131014,
                      "title": "Request for url https://URL.jpg failed with error: 404 (Not Found)"
                    }
                  ]
                }
              ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Received Callback from a Quick Reply Button Click

When your customer clicks on a quick reply button in an interactive message template, a response is sent. Below is an example of the callback format.

{
  "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": "WHATSAPP_ID"
                }
              ],
              "messages": [
                {
                  "context": {
                    "from": "PHONE_NUMBER",
                    "id": "wamid.ID"
                  },
                  "from": "16315551234",
                  "id": "wamid.ID",
                  "timestamp": "TIMESTAMP",
                  "type": "button",
                  "button": {
                    "text": "No",
                    "payload": "No-Button-Payload"
                  }
                }
              ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}