LiSco SMSالتوثيق
لوحة التحكمEnglish
  • مقدمة
  • البدء السريع
  • المصادقة
  • الأخطاء
  • الحدود
  • أرقام الهواتف
  • الرسائل
  • حالات الرسائل
  • رموز التحقق
  • الأجهزة
  • Webhooks
  • سجل التغييرات

© 2026 LiSco SMS

الشروطالخصوصيةحذف الحسابتواصل معنا

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-Typeapplication/json
User-AgentLiScoSMS-Webhooks/1.0
LiSco-Eventنوع الحدث، مثل message.delivered.
LiSco-Deliveryمعرّف الحدث. يبقى هو نفسه في كل إعادة محاولة لهذا الحدث: استخدمه لتجاهل التكرار.
LiSco-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256>

التحقق من التوقيع#

القيمة v1 هي HMAC-SHA256 للنص <t>.<raw body> بسرّ التوقيع، بالصيغة الست عشرية. قبل الوثوق بأي حدث:

  1. احسب HMAC على جسم الطلب الخام بايتًا بايتًا، لا على JSON أُعيد تنسيقه.
  2. قارنه مع v1 بزمن ثابت.
  3. ارفض الأحداث التي يبتعد فيها 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 ثوانٍ، وأنجز الأعمال البطيئة بعد الرد. وأي شيء آخر (خطأ أو إعادة توجيه أو انتهاء المهلة) يُعدّ فشلًا وتُعاد محاولة الحدث:

المحاولةبعد المحاولة السابقة بـ
230 ثانية
3دقيقتين
410 دقائق
530 دقيقة
6ساعتين
76 ساعات

بعد 7 محاولات يُتخلّى عن الحدث. وتظهر كل محاولة في لوحة التحكم ضمن عمليات التسليم الأخيرة.

الترتيب والتكرار#

  • قد تصل الأحداث بغير ترتيبها: قد يصل message.sent المعاد بعد message.delivered. احكم بحالة الرسالة status ووقت updatedAt، لا بترتيب الوصول.
  • قد يصل الحدث أكثر من مرة (مثلًا إذا ضاع ردك). احفظ LiSco-Delivery وتجاوز المعرّفات التي عالجتها.
السابقالأجهزةالتاليسجل التغييرات