Create, update and delete webhooks by API (Fast2SMS webhook v2)

You can create, list, update and delete Fast2SMS webhooks from your own code with the webhook API at https://www.fast2sms.com/dev/webhook/v2/{service}, where {service} is sms, otp, whatsapp, rcs or voice. This is handy when you set up many accounts, deploy to new servers or change URLs often. This guide lists every field, shows how to build the body with placeholders, and gives working examples in cURL, PHP, Python and Node.js.

Endpoints

Action Method and path
List webhooks of a service GET /dev/webhook/v2/{service}
Create a webhook POST /dev/webhook/v2/{service}
Update a webhook PUT /dev/webhook/v2/{service}/{id}
Delete a webhook DELETE /dev/webhook/v2/{service}/{id}

Send your API key in the authorization header, as with the other Fast2SMS APIs. {id} is the wh_... ID from the list or create reply. Webhooks created by API appear in the panel under Webhook, and panel webhooks appear in the API list.

SMS Webhook page listing three webhooks: CleverTap SMS status (Inactive), Failed SMS alert with Event FAILED and an Entity ID, and Order DLR to CRM with Event ALL, each with URL and method
Webhooks you create by API show up in the same list.

Create a webhook step by step

  1. Decide the service, event and identity

    Pick the service (for example sms), the event you want (all, delivered or failed for SMS) and, if needed, the identity: an Entity ID for SMS, a WhatsApp number, or a Bot ID for RCS. Leave the identity out to cover all.

  2. Write the body template

    The payload is what we send to your URL. Use {{field}} placeholders; they are filled in for each report. The field lists are below.

  3. POST the webhook

    curl -X POST "https://www.fast2sms.com/dev/webhook/v2/sms" \
      -H "authorization: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"name":"Order DLR to CRM",
           "url":"https://example.com/webhooks/fast2sms/sms",
           "method":"POST","content_type":"application/json","event":"all",
           "payload":{"request_id":"{{request_id}}","mobile":"{{mobile}}","status":"{{status}}",
                      "reason":"{{status_description}}","udf1":"{{udf1}}","delivered_at":"{{delivery_time}}"},
           "header_key":["X-Webhook-Token"],"header_value":["change-this-long-random-value"]}'
  4. Save the webhook ID

    {"return":true,"message":"Webhook created successfully","data":{
     "id":"wh_...","name":"Order DLR to CRM","service":"sms","url":"https://example.com/webhooks/fast2sms/sms",
     "method":"POST","content_type":"application/json",
     "status":"active","event":"all","payload_type":"SIMPLIFIED","identity_id":null}}

    Keep data.id. You need it to update or delete this webhook.

  5. Test it

    In the panel, open the webhook’s row menu and click Test Webhook to send one request with sample values, then check Webhook Logs.

Fields

Field Required Values
name Yes Up to 191 characters
url Yes A public http or https URL. Localhost, internal and file URLs are refused
method No (POST) POST, GET or PUT
content_type No (JSON) application/json, application/x-www-form-urlencoded or application/xml
event No (all) sms and otp: all, delivered, failed. whatsapp and rcs: also sent, read, received (incoming messages). voice: all, answered, no_answer, busy, failed
identity_id No (all) sms: a DLT Entity ID. whatsapp: one of your numbers. rcs: a Bot ID
template No (custom) custom (Standard). clevertap for sms and otp, clevertap_whatsapp or meta_direct for whatsapp, clevertap_rcs for rcs. Voice: custom only
payload Send it for custom The body template, as a JSON object or a string
header_key, header_value No Two lists of the same length with your custom headers
status No (active) active or inactive

Send custom headers as header_key and header_value lists. A headers object, as shown in some older examples, is not used. And always include a payload for a custom webhook: the request body is built only from your template.

Placeholders you can use

Service Placeholders
SMS request_id, route, sender_id, delivery_attempt, character_count, mobile, status, status_description, description, failure_reason, udf1, udf2, udf3, sms_language, sms_count, amount_debited, sent_timestamp, sent_time, delivery_timestamp, delivery_time
OTP All SMS fields, plus channel (sms or whatsapp), type, phone_number_id, recipient_id, category
WhatsApp request_id, mobile, status, status_description, udf1 to udf3, phone_number_id, display_phone_number, waba_id, recipient_id, category, webhook_type, message_id, from, message_type, body, media_url, mime_type, caption, context_message_id, timestamp, amount_debited, sent_time, delivery_time
RCS request_id, mobile, status, status_description, udf1 to udf3, error_message, failure_reason, description, webhook_type, message_id, from, message_type, body, media_url, mime_type, caption, timestamp
Voice request_id, campaign_name, mobile, status, description, duration, agent_duration, pulses, amount_debited, dtmf, agent_number, start_time, end_time, reason, timestamp

Write placeholders as {{status}} or @{{status}}; the panel uses the second form. Values are escaped for JSON automatically. For incoming WhatsApp messages and button replies, see receive incoming WhatsApp messages.

List, update and delete

List

curl "https://www.fast2sms.com/dev/webhook/v2/sms" -H "authorization: YOUR_API_KEY"

The reply is {"return":true,"data":[...]} with the same fields as the create reply for each webhook.

Update

An update replaces the whole webhook. Send every setting you want to keep: fields you leave out go back to their defaults (POST, JSON, all events, active, no identity, no headers).

curl -X PUT "https://www.fast2sms.com/dev/webhook/v2/sms/wh_YOUR_WEBHOOK_ID" \
  -H "authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Order DLR to CRM","url":"https://new.example.com/webhooks/fast2sms/sms",
       "method":"POST","content_type":"application/json","event":"failed",
       "payload":{"request_id":"{{request_id}}","mobile":"{{mobile}}","status":"{{status}}","reason":"{{status_description}}"},
       "header_key":["X-Webhook-Token"],"header_value":["change-this-long-random-value"]}'

Success: “Webhook updated successfully”. To pause a webhook without deleting it, send the same settings with "status":"inactive".

Delete

curl -X DELETE "https://www.fast2sms.com/dev/webhook/v2/sms/wh_YOUR_WEBHOOK_ID" \
  -H "authorization: YOUR_API_KEY"

Success: “Webhook deleted successfully”.

Code examples (create)

PHP

<?php
$webhook = [
    "name"         => "Order DLR to CRM",
    "url"          => "https://example.com/webhooks/fast2sms/sms",
    "event"        => "all",
    "payload"      => ["request_id" => "{{request_id}}", "mobile" => "{{mobile}}", "status" => "{{status}}"],
    "header_key"   => ["X-Webhook-Token"],
    "header_value" => ["change-this-long-random-value"],
];
$ch = curl_init("https://www.fast2sms.com/dev/webhook/v2/sms");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["authorization: YOUR_API_KEY", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS     => json_encode($webhook),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
echo ($data["return"] ?? false) === true ? $data["data"]["id"] : json_encode($data);

Python

import requests

webhook = {
    "name": "Order DLR to CRM",
    "url": "https://example.com/webhooks/fast2sms/sms",
    "event": "all",
    "payload": {"request_id": "{{request_id}}", "mobile": "{{mobile}}", "status": "{{status}}"},
    "header_key": ["X-Webhook-Token"],
    "header_value": ["change-this-long-random-value"],
}
r = requests.post("https://www.fast2sms.com/dev/webhook/v2/sms",
                  headers={"authorization": "YOUR_API_KEY"}, json=webhook, timeout=30)
data = r.json()
print(data["data"]["id"] if data.get("return") else data)

Node.js

const res = await fetch("https://www.fast2sms.com/dev/webhook/v2/sms", {
  method: "POST",
  headers: { authorization: process.env.FAST2SMS_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Order DLR to CRM",
    url: "https://example.com/webhooks/fast2sms/sms",
    event: "all",
    payload: { request_id: "{{request_id}}", mobile: "{{mobile}}", status: "{{status}}" },
    header_key: ["X-Webhook-Token"],
    header_value: ["change-this-long-random-value"],
  }),
});
const data = await res.json();
console.log(data.return === true ? data.data.id : data);

When webhooks fire

  • Delivery webhooks fire for messages sent through the API, for reports that arrive within 24 hours. Panel campaigns do not trigger them.
  • The webhook must be active, and its event and identity must match the report.
  • We wait up to 10 seconds for your answer. Network errors, timeouts, HTTP 408, 429 and 5xx are retried up to 3 times, 60 seconds apart.
  • Every attempt is in Webhook Logs for 7 days, and each log row can be resent once.
  • If the signature setting is on for your account, each request also has the header webhook_secret_key, a plain shared secret (not an HMAC).

Full details are in webhooks in Fast2SMS.

Common problems and fixes

“Limit reached: Maximum 10 webhooks allowed for SMS”

Each service allows 10 webhooks. Delete old ones or reuse one with a broader event.

“Webhook URL must be a public http(s) endpoint…”

Use a public URL. Localhost, private IPs and non-http links are not allowed.

“Webhook not found or does not belong to you.” (HTTP 404)

The {id} is wrong, belongs to another account, or is for a different service than the one in the path.

Validation errors such as a missing name

Send both name and url, on create and on every update.

My custom headers are missing

Use the header_key and header_value lists, not a headers object.

Error 412 or 414 (HTTP 401)

Check the API key, and whitelist your server IP if API Security is on. See API Security.

Frequently asked questions

Can I create Fast2SMS webhooks by API?

Yes. POST to /dev/webhook/v2/{service} with at least name and url.

Which services support webhooks?

SMS, OTP, WhatsApp, RCS and Voice.

Does an update change only the fields I send?

No. An update replaces the webhook, so send the full set of settings each time.

Can I send form data instead of JSON?

Yes. Set content_type to application/x-www-form-urlencoded and send the payload as an object; its keys become form fields.

Can I use the CleverTap format by API?

Yes. Set template to clevertap for SMS and OTP, clevertap_whatsapp for WhatsApp or clevertap_rcs for RCS. See CleverTap webhook integration.