WhatsApp Webhook Overview

Fast2SMS can send real-time WhatsApp delivery updates and incoming customer messages as a POST request (JSON or URL-encoded) or GET request to your configured webhook URL.

Webhook Formats

When creating a webhook, you can select one of the following formats under Select Format:

Standard Webhook (custom): Fully customizable. Allows configuration of Select Event, Method, Content-Type, and Body (payload). X-Payload-Transform is shown only when Content-Type is Form URL Encoded.
CleverTap (WhatsApp) (clevertap_whatsapp): Integrates directly with CleverTap's webhook callback structure. Select Event, Method, Content-Type, and Body are locked (read-only) when this template is selected.
META DIRECT (meta_direct): Matches the standard webhook payload structure sent directly by Meta for WhatsApp Business Cloud API. Select Event, Method, Content-Type, and Body are locked (read-only) when this template is selected.

Webhook Panel Form Options

When configuring a webhook in the Fast2SMS Dashboard under CREATE WEBHOOK, the fields correspond to the API parameters as follows:

Field Label in UI	API Parameter	Description & Visibility Rules
Webhook Name	`name`	Friendly name for internal tracking.
Select Service	`service`	Choose `WhatsApp` to configure WhatsApp webhooks.
Select Format	`template`	Choose `Standard Webhook`, `CleverTap (WhatsApp)`, or `META DIRECT`.
Select Event	`event`	Filter trigger events (e.g. `Default All Events`, `On Sent`, `On Delivered`, `On Read`, `On Failed`, `Incoming Messages`). Locked if format is not Standard Webhook.
Phone Number Id	`identity_id`	Optional WABA Phone Number ID. Defaults to "Default All". Only shown when Service is WhatsApp.
Method	`method`	HTTP method (`POST`, `GET`, `PUT`). Locked if format is not Standard Webhook.
URL	`url`	Destination URL to receive payloads.
Content-Type	`content_type`	Target encoding format (`JSON`, `Form URL Encoded`, `XML`). Locked if format is not Standard Webhook.
X-Payload-Transform	`payload_transform`	Transform level (`Standard`, `Raw JSON`). Shown only when Content-Type is Form URL Encoded.
Webhook Status (Active)	`status`	Switch to enable/disable webhook triggers (`active`/`inactive`).
Body	`payload`	Custom payload structure text. Locked if format is not Standard Webhook.

Standard Webhook Payload

Payload Variables

Variable	Type	Description
`request_id`	String	Unique request identifier for the message
`route`	String	The service route (e.g., `response` or `whatsapp`)
`sender_id`	String	The Sender ID / phone number of the sender
`delivery_attempt`	Integer	Number of delivery attempts
`character_count`	Integer	Character count of the message text
`mobile`	String	Recipient 10-digit mobile number
`status`	String	Delivery status (e.g., `delivered`, `failed`, `received`)
`status_description`	String	Detailed status text
`udf1`	String	User Defined Field 1 – Optional custom value passed via API and returned in the webhook for your internal reference or tracking.
`udf2`	String	User Defined Field 2 – Optional custom value passed via API and returned in the webhook for your internal reference or tracking.
`udf3`	String	User Defined Field 3 – Optional custom value passed via API and returned in the webhook for your internal reference or tracking.
`phone_number_id`	String	WhatsApp phone number ID
`display_phone_number`	String	Display phone number
`waba_id`	String	WhatsApp Business Account ID
`recipient_id`	String	Recipient phone number
`category`	String	Message category (e.g., `UTILITY`, `AUTHENTICATION`)
`mime_type`	String	Media MIME type if media message (e.g., `text/plain`, `image/png`)
`media_url`	String	Media file URL if media message
`caption`	String	Media caption text if media message
`from`	String	Sender phone number (for incoming messages)
`message_type`	String	Message type (e.g., `text`, `image`)
`body`	String	Message text body (for incoming messages)
`post_attempt`	Integer	Webhook retry attempt count
`webhook_type`	String	Event type (e.g., `status_update`, `incoming_message`)

Example JSON Payload (Status Update)

{
  "request_id": "Wabcdef12345678",
  "route": "response",
  "sender_id": "GLOBAL",
  "delivery_attempt": 1,
  "character_count": 120,
  "mobile": "9999999999",
  "status": "delivered",
  "status_description": "Delivered successfully",
  "udf1": "TEST-CLIENT-ID",
  "udf2": "TEST-CRQID",
  "udf3": "TEST-UUID-1234",
  "phone_number_id": "109283746561",
  "display_phone_number": "9999999999",
  "waba_id": "1283746561092",
  "recipient_id": "9999999999",
  "category": "UTILITY",
  "post_attempt": 1,
  "webhook_type": "status_update"
}

Example JSON Payload (Incoming Message)

{
  "phone_number_id": "109283746561",
  "display_phone_number": "9999999999",
  "waba_id": "1283746561092",
  "from": "919999999999",
  "message_type": "text",
  "body": "This is a test message body.",
  "webhook_type": "incoming_message"
}

CleverTap (WhatsApp) Webhook Payload

If you select the CleverTap (WhatsApp) format, the payload will be structured as follows:

Example JSON Payload (CleverTap WhatsApp)

{
  "payloadVersion": "1",
  "statuses": [
    {
      "msgId": "Wabcdef12345678",
      "status": "delivered",
      "timestamp": "1718712002",
      "description": "Delivered successfully"
    }
  ]
}

META DIRECT Webhook Payload

If you select the META DIRECT format, the payload will mimic the structure directly dispatched by Meta's Cloud API:

Example JSON Payload (META DIRECT)

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "109283746561",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "9999999999",
              "phone_number_id": "109283746561"
            },
            "statuses": [
              {
                "id": "Wabcdef12345678",
                "status": "delivered",
                "timestamp": "1718712002",
                "recipient_id": "9999999999"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}