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#
| Type | When |
|---|---|
message.sent | A message you sent through the API (or an OTP code) was sent by a phone. |
message.delivered | The network confirmed delivery. |
message.failed | The message failed for good. |
message.expired | It expired before it was sent. |
device.offline | A phone hasn't pulled for 60 seconds (sent once until it is back). |
webhook.test | You 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.
{
"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"
}
}{
"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"
}
}{
"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"
}
}{
"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:
{
"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"
}
}{
"id": "evt_Xa0cV5nM2kQ8rTbL6wPz1DyS",
"type": "webhook.test",
"createdAt": "2026-11-20T09:00:00.000Z",
"data": {}
}Headers#
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | LiScoSMS-Webhooks/1.0 |
LiSco-Event | The event type, e.g. message.delivered. |
LiSco-Delivery | The event id. The same on every retry of this event: use it to ignore duplicates. |
LiSco-Signature | t=<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:
- Compute the HMAC over the raw request body, byte for byte, not over re-serialized JSON.
- Compare it with
v1in constant time. - Reject events whose
tis 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 sResponding 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:
| Attempt | After the previous one |
|---|---|
| 2 | 30 seconds |
| 3 | 2 minutes |
| 4 | 10 minutes |
| 5 | 30 minutes |
| 6 | 2 hours |
| 7 | 6 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.sentmay arrive aftermessage.delivered. Decide by the message'sstatusandupdatedAt, not by arrival order. - An event can arrive more than once (for example if your answer was lost). Store
LiSco-Deliveryand skip ids you have already handled.