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

WebhookParameterWhen SMSEdge sends it
Delivery report (DLR)dlr_urlA delivery report arrives from the network for an SMS that you sent through the API. It is sent again when a newer report arrives.
Clickclick_urlThe recipient clicks a short link in your SMS. Sent one time for each message.
Inbound SMSinbound_urlSomeone sends an SMS to one of your dedicated numbers.
Click revokedrevoke_click_urlSMSEdge 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

  1. Open API settings.
  2. In Webhook URLs, type your URLs in DLR Webhook URL, Inbound SMS URL and Click Webhook URL.
  3. 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"
}
FieldDescription
sms_id, idThe SMS id that Send a single SMS returned. Both fields have the same value.
referenceThe reference that you sent with the message.
statusWhat SMSEdge did with the message: waiting, sent or failed.
dlr_statusThe delivery report from the network. Usual values: Delivered, Enroute, Accepted, Expired, Undeliverable, Rejected, Failed and Unknown.
clickedtrue when the recipient clicked the short link.
cost, partsThe 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 201 and 204.
  • SMSEdge does not follow redirects. A 301 or 302 is 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 2xx status. 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);