LiSco SMSDocs
Dashboardالعربية
  • Introduction
  • Quick start
  • Authentication
  • Errors
  • Limits
  • Phone numbers
  • Messages
  • Message statuses
  • OTP codes
  • Devices
  • Webhooks
  • Changelog

© 2026 LiSco SMS

TermsPrivacyDelete accountContact

Webhooks

Instead of polling, let LiSco SMS call your server whenever something happens.

Setup#

In the dashboard open API keys & webhooks → Webhook, enter your endpoint URL, choose the events and save. Webhooks are available on the Starter plan and above. After saving you can Reveal the signing secret (whsec_…) and Send test event.

In production the URL must be https:// and must not point to a private or local network.

Events#

TypeWhen
message.sentA message you sent through the API (or an OTP code) was sent by a phone.
message.deliveredThe network confirmed delivery.
message.failedThe message failed for good.
message.expiredIt expired before it was sent.
device.offlineA phone hasn't pulled for 60 seconds (sent once until it is back).
webhook.testYou pressed Send test event. Always sent, whatever events you chose.

Test messages sent from the dashboard don't produce message events.

Payload#

Every event is a POST with a JSON body: id (the event id), type, createdAt and data. For message events, data is the message object, exactly as GET /v1/messages/{id} returns it but without events.

Payload
{
  "id": "evt_3kQd8VnP2xLmRt7YcWb0aZ9e",
  "type": "message.delivered",
  "createdAt": "2026-11-20T09:15:09.322Z",
  "data": {
    "id": "6650f1c2e4b0a1b2c3d4e5f6",
    "to": "+905321234567",
    "text": "Order #1042 is ready for pickup.",
    "status": "delivered",
    "deviceId": "6650e0a1e4b0a1b2c3d4e500",
    "sim": 1,
    "error": null,
    "requestId": null,
    "createdAt": "2026-11-20T09:15:02.481Z",
    "updatedAt": "2026-11-20T09:15:09.210Z",
    "expiresAt": "2026-11-21T09:15:02.481Z"
  }
}
Payload
{
  "id": "evt_9TfLq2Rk7VbN4cXw1MzP0aHs",
  "type": "message.sent",
  "createdAt": "2026-11-20T09:15:06.230Z",
  "data": {
    "id": "6650f1c2e4b0a1b2c3d4e5f6",
    "to": "+905321234567",
    "text": "Order #1042 is ready for pickup.",
    "status": "sent",
    "deviceId": "6650e0a1e4b0a1b2c3d4e500",
    "sim": 1,
    "error": null,
    "requestId": null,
    "createdAt": "2026-11-20T09:15:02.481Z",
    "updatedAt": "2026-11-20T09:15:06.114Z",
    "expiresAt": "2026-11-21T09:15:02.481Z"
  }
}
Payload
{
  "id": "evt_Ww4bX8nR1qPz6KcT3mLd0YsV",
  "type": "message.failed",
  "createdAt": "2026-11-20T09:16:40.010Z",
  "data": {
    "id": "6650f1c2e4b0a1b2c3d4e5f6",
    "to": "+905321234567",
    "text": "Order #1042 is ready for pickup.",
    "status": "failed",
    "deviceId": "6650e0a1e4b0a1b2c3d4e500",
    "sim": 2,
    "error": "generic_failure",
    "requestId": null,
    "createdAt": "2026-11-20T09:15:02.481Z",
    "updatedAt": "2026-11-20T09:16:39.901Z",
    "expiresAt": "2026-11-21T09:15:02.481Z"
  }
}
Payload
{
  "id": "evt_Lr6yB2vN8xQk0TcW4mPz7DaS",
  "type": "message.expired",
  "createdAt": "2026-11-21T09:15:30.004Z",
  "data": {
    "id": "6650f1c2e4b0a1b2c3d4e5f6",
    "to": "+905321234567",
    "text": "Order #1042 is ready for pickup.",
    "status": "expired",
    "deviceId": null,
    "sim": null,
    "error": "expired",
    "requestId": null,
    "createdAt": "2026-11-20T09:15:02.481Z",
    "updatedAt": "2026-11-21T09:15:29.950Z",
    "expiresAt": "2026-11-21T09:15:02.481Z"
  }
}

device.offline carries the phone:

Payload
{
  "id": "evt_Qp1dZ7mK3vR9xNcB5tLw2YeH",
  "type": "device.offline",
  "createdAt": "2026-11-20T11:42:31.118Z",
  "data": {
    "id": "6650e0a1e4b0a1b2c3d4e500",
    "name": "Shop phone",
    "lastSeenAt": "2026-11-20T11:41:28.640Z"
  }
}
Payload
{
  "id": "evt_Xa0cV5nM2kQ8rTbL6wPz1DyS",
  "type": "webhook.test",
  "createdAt": "2026-11-20T09:00:00.000Z",
  "data": {}
}

Headers#

HeaderValue
Content-Typeapplication/json
User-AgentLiScoSMS-Webhooks/1.0
LiSco-EventThe event type, e.g. message.delivered.
LiSco-DeliveryThe event id. The same on every retry of this event: use it to ignore duplicates.
LiSco-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256>

Verify the signature#

v1 is the HMAC-SHA256 of <t>.<raw body> with your signing secret, in hex. Before trusting an event:

  1. Compute the HMAC over the raw request body, byte for byte, not over re-serialized JSON.
  2. Compare it with v1 in constant time.
  3. Reject events whose t is more than 5 minutes away from your clock (replays).
// Node 18+ — Express. Use the RAW body: the signature covers the exact bytes.
import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.LISCO_WEBHOOK_SECRET; // whsec_…
const TOLERANCE_SECONDS = 5 * 60;

function verify(header, rawBody, secret) {
  if (!header) return false;
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(parts.v1 ?? "")) return false;
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false; // too old: replay
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1, "hex");
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

const seen = new Set(); // use your database in production

const app = express();
app.post("/webhooks/lisco", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verify(req.get("LiSco-Signature"), raw, SECRET)) return res.sendStatus(400);

  const deliveryId = req.get("LiSco-Delivery");
  if (seen.has(deliveryId)) return res.sendStatus(200); // a retry we already handled
  seen.add(deliveryId);

  const event = JSON.parse(raw);
  console.log(event.type, event.data.id, event.data.status);
  res.sendStatus(200); // answer within 10 s; do slow work afterwards
});

app.listen(3000);
<?php
// PHP 8+. Read the RAW body: the signature covers the exact bytes.
$secret = getenv("LISCO_WEBHOOK_SECRET"); // whsec_…
$tolerance = 5 * 60;

function lisco_verify(?string $header, string $rawBody, string $secret, int $tolerance): bool {
    if (!$header) return false;
    $parts = [];
    foreach (explode(",", $header) as $part) {
        [$k, $v] = array_pad(explode("=", trim($part), 2), 2, "");
        $parts[$k] = $v;
    }
    $t = $parts["t"] ?? "";
    $v1 = $parts["v1"] ?? "";
    if (!ctype_digit($t) || !preg_match('/^[0-9a-f]{64}$/', $v1)) return false;
    if (abs(time() - (int) $t) > $tolerance) return false; // too old: replay
    $expected = hash_hmac("sha256", $t . "." . $rawBody, $secret);
    return hash_equals($expected, $v1); // constant-time
}

$raw = file_get_contents("php://input");
$header = $_SERVER["HTTP_LISCO_SIGNATURE"] ?? null;
if (!lisco_verify($header, $raw, $secret, $tolerance)) {
    http_response_code(400);
    exit;
}

$deliveryId = $_SERVER["HTTP_LISCO_DELIVERY"] ?? "";
// if (already_processed($deliveryId)) { http_response_code(200); exit; }

$event = json_decode($raw, true);
error_log($event["type"] . " " . ($event["data"]["id"] ?? ""));
http_response_code(200); // answer within 10 s
# Python 3.9+ — Flask. Use the RAW body: the signature covers the exact bytes.
import hashlib, hmac, os, re, time
from flask import Flask, request, abort

SECRET = os.environ["LISCO_WEBHOOK_SECRET"]  # whsec_…
TOLERANCE_SECONDS = 5 * 60
app = Flask(__name__)
seen = set()  # use your database in production


def verify(header, raw_body: bytes, secret: str) -> bool:
    if not header:
        return False
    parts = dict(p.strip().split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or not re.fullmatch(r"[0-9a-f]{64}", v1):
        return False
    if abs(time.time() - int(t)) > TOLERANCE_SECONDS:  # too old: replay
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)  # constant-time


@app.post("/webhooks/lisco")
def lisco_webhook():
    raw = request.get_data()  # bytes, exactly as sent
    if not verify(request.headers.get("LiSco-Signature"), raw, SECRET):
        abort(400)
    delivery_id = request.headers.get("LiSco-Delivery")
    if delivery_id in seen:
        return "", 200  # a retry we already handled
    seen.add(delivery_id)
    event = request.get_json()
    print(event["type"], event["data"].get("id"))
    return "", 200  # answer within 10 s
Rotating the secret in the dashboard takes effect immediately: events after that, including retries of older events, are signed with the new secret. Update your server right away.

Responding and retries#

Answer with any 2xx within 10 seconds. Do slow work after answering. Anything else (an error, a redirect, a timeout) counts as a failure and the event is retried:

AttemptAfter the previous one
230 seconds
32 minutes
410 minutes
530 minutes
62 hours
76 hours

After 7 attempts the event is given up. Every attempt is listed in the dashboard under Recent deliveries.

Order and duplicates#

  • Events can arrive out of order: a retried message.sent may arrive after message.delivered. Decide by the message's status and updatedAt, not by arrival order.
  • An event can arrive more than once (for example if your answer was lost). Store LiSco-Delivery and skip ids you have already handled.
PreviousDevicesNextChangelog