SMS Webhook Overview

Fast2SMS can send real-time SMS delivery updates 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 (SMS) (clevertap): Integrates directly with CleverTap's webhook callback structure. 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 `SMS` to configure SMS delivery webhooks.
Select Format	`template`	Choose `Standard Webhook` or `CleverTap (SMS)`.
Select Event	`event`	Filter trigger events (e.g. `Default All Events`, `On Delivered`, `On Failed`). Locked if format is not Standard Webhook.
Entity ID	`identity_id`	Optional Entity ID. Defaults to "Default All". Only shown when Service is SMS.
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 SMS route used (e.g., `dlt`, `dlt_manual`)
`sender_id`	String	The Sender ID
`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`)
`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.
`server_id`	Integer	The server ID associated with the log
`sms_language`	String	Message encoding language (`english`, `unicode`)
`sms_count`	Integer	Number of split message parts
`amount_debited`	String	Balance debited for this message
`sent_timestamp`	Integer	Unix timestamp when the message was sent
`sent_time`	String	Formatted date-time string when sent
`delivery_timestamp`	Integer	Unix timestamp when the message was delivered
`delivery_time`	String	Formatted date-time string when delivered
`failure_reason`	String	Description of the error if delivery failed
`description`	String	Event status overview
`post_attempt`	Integer	Webhook retry attempt count
`webhook_type`	String	Event type (e.g., `status_update`)

Example JSON Payload (Standard Webhook)

{
  "request_id": "Sabcdef12345678",
  "route": "dlt",
  "sender_id": "FSTSMS",
  "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",
  "server_id": 12345,
  "sms_language": "english",
  "sms_count": 1,
  "amount_debited": "0.2000",
  "sent_timestamp": 1718712000,
  "sent_time": "2026-06-18 12:00:00",
  "delivery_timestamp": 1718712002,
  "delivery_time": "2026-06-18 12:00:02",
  "failure_reason": "Delivered successfully",
  "description": "Delivered successfully",
  "post_attempt": 1,
  "webhook_type": "status_update"
}

CleverTap (SMS) Webhook Payload

If you select the CleverTap (SMS) format, the payload will be structured as follows to match CleverTap requirements:

Example JSON Payload (CleverTap SMS)

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