Callback URL WhatsApp Business

Configure a callback URL to receive real-time status updates for your outbound WhatsApp messages.

Create an endpoint that accepts POST requests with a JSON body.
Provide the endpoint URL using the following structure.

POST https://YourDomain/YourPath

📘
POST Request
Send WhatsApp Message API will make a POST request to your URL.

After you send a message, the callback URL receives the following event parameters:

Parameter	Description
callback	Webhook URL to notify about the events of the whatsApp message. Date when the API receives the WhatsApp message status. The date is represented with date in UTC Zulu format: (yyyy-mm-dd-Thh:mm:ss.ssZ).
date	Date when the API receives the WhatsApp message status. The date is represented with date in UTC Zulu format: (yyyy-mm-dd-Thh:mm:ss.ssZ).
externalId	Alphanumeric identifier used to identify your whatsApp messages uniquely for reporting purposes.
campaignId	Broadcast identifier that can be used for reporting purposes. This is an identifier you can use to uniquely identify the destination address in your systems. This is similar to the externalId and will be sent back to you if you are requesting callbacks that contain status changes of the messages you send.
from	Shortcode (from 1 to 6 digits), Longcode (from 7 digits on), an alphanumeric shortcode (ex. COMPANY) or a virtual number used to originate and send the whatsApp message
id	Unique identifier of the WhatsApp message.
providerId	Unique message identifier assigned by Meta.
to	Destination address of the message.
message	Content of the whatsApp message that was sent to the end user.
username	Owner or creator of the WhatsApp message.
status	When a whatsApp Message is sent, the system assigns one of the following possible statuses to an message: `SENT`: Message was sent to the outbound delivery system. `DELIVERED`: Message was delivered to the end-device of the user. `READ`: Message has been opened or acknowledged by the end user. Note: The READ status may not be displayed because an end user can block the read option. `CODE_NOT_ALLOWED`: Sender of the WhatsApp Business Account is not valid to send the message. `FAILED`: Message delivery failed. `QUOTA_EXCEEDED`: WhatsApp Business Account exceeded the message sending limit. For more information about Messaging Limits go to: Capacity, Quality Rating, and Messaging Limits section. `EXPIRED`: Message was too old to be sent. `INCOMPLETE`: Applies to messages based on message templates. Placeholders (personalized fields) of the message sent through message templates must be complete.
detail	Only applies if the `"status"` is `"FAILED"`. Provides more context about why a message failed. This enhancement helps users understand the specific reason behind a failed delivery. For example: `"Re-engagement message. Message failed to send because more than 24 hours have passed since the customer last replied to this number."`
webhook	Origin of the event. `true`: The event originated if the service provider (meta) sent us the information. That is, if meta reports any event, it will be true. `false`: The event originated if we sent the information. That is, if we report any event, it will be false.

The following callback payloads show how the status and detail fields vary by delivery outcome:

A successfully sent message has a "SENT" status and does not include the "detail" field.
A failed message has a "FAILED" status and includes a "detail" field that explains the failure.

Successful Send

{
  "callback": "https://webhook.site/45654",
  "date": "2023-01-02T19:35:19.300Z",
  "externalId": "external-id-001",
  "campaignId": null,
  "from": "130523",
  "id": "id.HBgIxNTU2",
  "providerId": "wamid.45675",
  "to": "+105500000000",
  "message": "message text body",
  "username": "development",
  "status": "SENT",
  "webhook": true
}

Failed Send

{
  "callback": "https://webhook.site/45654",
  "date": "2023-01-02T19:35:19.300Z",
  "externalId": "external-id-001",
  "campaignId": null,
  "from": "130523",
  "id": "id.HBgIxNTU2",
  "providerId": "wamid.45675",
  "to": "+105500000000",
  "message": "message text body",
  "username": "development",
  "status": "FAILED",
  "detail": "Re-engagement message. Message failed to send because more than 24 hours have passed since the customer last replied to this number.",
  "webhook": true
}