API guide
Webhooks
Webhooks send events to your server when they occur, so you do not have to poll the API. SMSEdge sends an HTTP POST to a URL that you set.
Webhook types
| Webhook | Parameter | When SMSEdge sends it |
|---|---|---|
| Delivery report (DLR) | dlr_url | A delivery report arrives from the network for an SMS that you sent through the API. It is sent again when a newer report arrives. |
| Click | click_url | The recipient clicks a short link in your SMS. Sent one time for each message. |
| Inbound SMS | inbound_url | Someone sends an SMS to one of your dedicated numbers. |
| Click revoked | revoke_click_url | SMSEdge finds that clicks came from bots and removes them from your statistics. |
Delivery report and click webhooks are for messages sent with Send a single SMS. SMSEdge sends them only for messages that are less than 24 hours old.
Set your webhook URLs
In the app
- Open API settings.
- In Webhook URLs, type your URLs in DLR Webhook URL, Inbound SMS URL and Click Webhook URL.
- Click Update Webhooks.
The click revoked URL and Basic authentication are available only through the API.
Through the API
Use Set webhook URLs. Send only the URLs that you want to change. To remove a URL, send it as an empty string.
curl -X POST https://api.smsedge.com/v1/user/set-webhook/ \
-H "X-API-KEY: YOUR_API_KEY" \
-d "dlr_url=https://example.com/smsedge/dlr" \
-d "click_url=https://example.com/smsedge/click" \
-d "inbound_url=https://example.com/smsedge/inbound" \
-d "revoke_click_url=https://example.com/smsedge/revoke" \
-d "auth=smsedge:s3cret-pass"
To read the current URLs, use Get webhook URLs. The auth field there is only true or false. The API never returns the password.
Test your endpoint
Send POST /v1/user/test-webhook/ to get one test event at each URL that you set. Test events have "test": true. The response tells you, for each webhook, if your server answered with HTTP 200.
curl -X POST https://api.smsedge.com/v1/user/test-webhook/ \
-H "X-API-KEY: YOUR_API_KEY"
"data": {
"dlr": { "status": "ok", "http_code": 200, "time": 0.245 },
"click": { "status": "failed", "http_code": 500, "time": 0.156 },
"inbound": { "status": "skipped", "reason": "not configured" },
"revoke_click": { "status": "ok", "http_code": 200, "time": 0.132 }
}
Request format
All four webhooks use the same format:
- Method:
POST. - Content type:
application/x-www-form-urlencoded; charset=utf-8. - Body: one form field named
sms. Its value is a JSON string with the event.
The body is not raw JSON. Read the sms form field first, then decode its value as JSON.
Delivery report payload
{
"sms_id": 123456789,
"id": 123456789,
"created": "2026-11-16 14:30:00",
"updated": "2026-11-16 14:30:07",
"from": "Acme",
"to": 447700900123,
"verify_local": 1,
"shorten_url": 1,
"list_id": null,
"reference": "order-1042",
"transactional": 0,
"preferred_route_id": null,
"campaign_id": null,
"delay_time": null,
"country_id": 225,
"country_name": "United Kingdom",
"country_iso": "GB",
"conversion_key": "api-1116-12345678901",
"conversion_pixel": {
"lead": "http://edgepxl.com/postback.php?type=lead&key=api-1116-12345678901",
"sale": "http://edgepxl.com/postback.php?type=sale&key=api-1116-12345678901"
},
"clicked": false,
"cost": 0.0175,
"parts": 1,
"original_url": "https://example.com/track/1042",
"shortened_url": "https://exmpl.link/aB3dE",
"text": "Your order 1042 has shipped. Track it: https://exmpl.link/aB3dE",
"status": "sent",
"dlr_status": "Delivered"
}
| Field | Description |
|---|---|
sms_id, id | The SMS id that Send a single SMS returned. Both fields have the same value. |
reference | The reference that you sent with the message. |
status | What SMSEdge did with the message: waiting, sent or failed. |
dlr_status | The delivery report from the network. Usual values: Delivered, Enroute, Accepted, Expired, Undeliverable, Rejected, Failed and Unknown. |
clicked | true when the recipient clicked the short link. |
cost, parts | The price of the message and the number of SMS parts. |
Fields without a value can be missing. For example, original_url and shortened_url are only there when the text has a link.
Click payload
The click webhook has the same fields as the delivery report, with "clicked": true. It needs a short link: send the message with shorten_url=1 (the default) and a URL in the text.
Inbound SMS payload
{
"id": 5678,
"from": "447700900123",
"to": 447700900999,
"message": "YES please",
"received": "2026-11-16 14:35:00"
}
from is the number of the person who sent the SMS. to is your dedicated number.
Click revoked payload
{
"event": "clicks_revoked",
"count": 3,
"api_sms_ids": [123456789, 123456790],
"campaign_sms_ids": [987654321]
}
api_sms_ids: SMS ids of messages sent through the API.campaign_sms_ids: ids of messages sent in campaigns.count: the total number of messages in the two arrays.
Mark these messages as not clicked in your system.
Authentication of webhook requests
If you set auth to username:password (maximum 32 characters), SMSEdge sends delivery report webhooks with HTTP Basic authentication. Check the Authorization header on your server. The other webhooks are sent without authentication, so use a URL that is hard to guess, for example one with a long random path.
Respond and retries
- Return HTTP 200 within 10 seconds. For delivery report, click and inbound webhooks, any other status code is a failure, also
201and204. - SMSEdge does not follow redirects. A
301or302is a failure. - After a failure, SMSEdge tries again after about 5 to 6 hours. Delivery report and click webhooks stop when the message is 24 hours old.
- Click revoked webhooks accept any
2xxstatus. SMSEdge tries 3 times, 6 hours apart.
Save the event and return 200 at once. Do the slow work later, in a queue. You can get the same event more than one time, so make your handler safe to run again. For example, use sms_id and dlr_status as a key.
Example receivers
// Node.js with Express
import express from 'express'
const app = express()
app.use(express.urlencoded({ extended: false }))
app.post('/smsedge/dlr', (req, res) => {
const event = JSON.parse(req.body.sms)
console.log(event.sms_id, event.reference, event.dlr_status)
// Save the event, then answer at once
res.sendStatus(200)
})
app.listen(3000)
# Python with Flask
import json
from flask import Flask, request
app = Flask(__name__)
@app.post("/smsedge/dlr")
def dlr():
event = json.loads(request.form["sms"])
print(event["sms_id"], event.get("reference"), event["dlr_status"])
return "", 200
<?php
// PHP
$event = json_decode($_POST['sms'] ?? '', true);
if (!is_array($event)) {
http_response_code(400);
exit;
}
error_log("SMS {$event['sms_id']} {$event['dlr_status']}");
http_response_code(200);