Webhooks
بدل الاستعلام المتكرر، دع LiSco SMS يستدعي خادمك كلما حدث شيء.
الإعداد#
في لوحة التحكم افتح مفاتيح API والـ Webhooks ← Webhook، وأدخل عنوان نقطة الاستقبال، واختر الأحداث، ثم احفظ. الـ Webhooks متاحة في خطة Starter وما فوقها. بعد الحفظ يمكنك إظهار سرّ التوقيع (whsec_…) وإرسال حدث تجريبي.
في بيئة الإنتاج يجب أن يبدأ العنوان بـ https:// وألا يشير إلى شبكة خاصة أو محلية.
الأحداث#
| النوع | متى |
|---|---|
message.sent | أرسل هاتف رسالة أرسلتها عبر الواجهة (أو رمز تحقق). |
message.delivered | أكّدت الشبكة التسليم. |
message.failed | فشلت الرسالة نهائيًا. |
message.expired | انتهت صلاحيتها قبل الإرسال. |
device.offline | لم يسحب هاتف طوال 60 ثانية (يُرسل مرة واحدة حتى يعود). |
webhook.test | ضغطت إرسال حدث تجريبي. يُرسل دائمًا مهما كانت الأحداث المختارة. |
الرسائل التجريبية المرسلة من لوحة التحكم لا تولّد أحداث رسائل.
الحمولة#
كل حدث طلب POST بجسم JSON فيه: id (معرّف الحدث) وtype وcreatedAt وdata. في أحداث الرسائل تكون data هي كائن الرسالة كما يعيده GET /v1/messages/{id} تمامًا، لكن دون 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 بيانات الهاتف:
{
"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": {}
}الترويسات#
| الترويسة | القيمة |
|---|---|
Content-Type | application/json |
User-Agent | LiScoSMS-Webhooks/1.0 |
LiSco-Event | نوع الحدث، مثل message.delivered. |
LiSco-Delivery | معرّف الحدث. يبقى هو نفسه في كل إعادة محاولة لهذا الحدث: استخدمه لتجاهل التكرار. |
LiSco-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256> |
التحقق من التوقيع#
القيمة v1 هي HMAC-SHA256 للنص <t>.<raw body> بسرّ التوقيع، بالصيغة الست عشرية. قبل الوثوق بأي حدث:
- احسب HMAC على جسم الطلب الخام بايتًا بايتًا، لا على JSON أُعيد تنسيقه.
- قارنه مع
v1بزمن ثابت. - ارفض الأحداث التي يبتعد فيها
tعن ساعتك أكثر من 5 دقائق (إعادة الإرسال الخبيثة).
// 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الرد وإعادة المحاولة#
ردّ بأي رمز 2xx خلال 10 ثوانٍ، وأنجز الأعمال البطيئة بعد الرد. وأي شيء آخر (خطأ أو إعادة توجيه أو انتهاء المهلة) يُعدّ فشلًا وتُعاد محاولة الحدث:
| المحاولة | بعد المحاولة السابقة بـ |
|---|---|
| 2 | 30 ثانية |
| 3 | دقيقتين |
| 4 | 10 دقائق |
| 5 | 30 دقيقة |
| 6 | ساعتين |
| 7 | 6 ساعات |
بعد 7 محاولات يُتخلّى عن الحدث. وتظهر كل محاولة في لوحة التحكم ضمن عمليات التسليم الأخيرة.
الترتيب والتكرار#
- قد تصل الأحداث بغير ترتيبها: قد يصل
message.sentالمعاد بعدmessage.delivered. احكم بحالة الرسالةstatusووقتupdatedAt، لا بترتيب الوصول. - قد يصل الحدث أكثر من مرة (مثلًا إذا ضاع ردك). احفظ
LiSco-Deliveryوتجاوز المعرّفات التي عالجتها.