Webhooks

الإعداد

أضف نقطة نهاية في Studio → API للمطورين: أدخل عنوان URL الخاص بك بصيغة HTTPS وحدّد الأحداث المراد الاشتراك فيها. يعرض PollsLive سرّ التوقيع (whsec_…) مرة واحدة فقط. احفظه للتحقق من عمليات التسليم.

الأحداث

• poll.published: A poll was published and is now live/shareable.
• poll.closed: Voting was closed on a poll.
• vote.created: A new vote was recorded on an async poll.
• session.started: A live presenter session was started.
• session.ended: A live presenter session ended.
• response.created: An async response was recorded. Live session answers do not emit this event.

الحمولة

كل عملية تسليم هي جسم JSON يحتوي على اسم الحدث وطابع زمني وبيانات الحدث:

{
  "event": "poll.published",
  "createdAt": "2026-06-18T12:00:00.000Z",
  "data": {
    "poll": { "id": "...", "slug": "...", "title": "...", "shareUrl": "..." }
  }
}

يحمل كل طلب أيضًا هذه الترويسات:

• X-PollsLive-Event: اسم الحدث.
• X-PollsLive-Delivery: معرّف تسليم فريد.
• X-PollsLive-Signature: t=<unix>,v1=<hex>.

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

احسب HMAC-SHA256 لـ <t>.<rawBody> باستخدام سرّ التوقيع الخاص بك وقارنه بقيمة v1 (بزمن ثابت):

import crypto from "crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(",").map((kv) => kv.split("="))
  );
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1)
  );
}

استجب بحالة 2xx للإقرار. ارفض أي شيء يفشل في التحقق.

إعادة المحاولات

إذا تعذّر الوصول إلى نقطة النهاية الخاصة بك أو أعادت حالة غير 2xx، يعيد PollsLive المحاولة بتراجع أُسّي (تقريبًا 1m، 5m، 30m، 2h، 6h) حتى ست محاولات. اجعل معالجك متساوي القوة (idempotent) باستخدام معرّف X-PollsLive-Delivery .