Webhooks

سجّل نقطة نهاية HTTPS وسيرسل إليها Debaty طلب POST بمجرد حدوث شيء ما.

import { createHmac, timingSafeEqual } from 'node:crypto';

// Verify a Debaty webhook delivery, and reject anything that does not verify.
//   secret: the whsec_… shown once when you created the subscription
//   header: the X-Debaty-Signature request header (t=<seconds>,v1=<hex>)
//   body:   the raw, unparsed request body
function verifyDebatySignature(secret, header, body, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp)) return false;

  // The timestamp is inside the signed material, so a captured delivery cannot be
  // replayed later under a fresh t — reject anything outside the window.
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > toleranceSeconds) return false;

  const expected = createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
  if (expected.length !== (parts.v1 ?? '').length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

1. سجّل نقطة نهاية

   أدخِل رابط HTTPS واختَر الأحداث التي تريد الاستماع إليها. في الواجهة البرمجية يُسمّى هذا الحقل eventTypes؛ والمرجع يذكر القيم التي يقبلها.

2. تحقّق من التوقيع

   كل عملية تسليم موقّعة بمفتاح الـ webhook السري الخاص بك. تحقّق من التوقيع قبل أن تثق به.

3. ردّ بسرعة

   ردّ برمز 2xx خلال ثوانٍ. عند حدوث خطأ، يعيد Debaty المحاولة.

4. ماذا يصلك، ومتى

   يصلك post.created وdebate.created وcomment.created. كل ما يُكتب عبر الـ API يُطلق الأحداث نفسها تمامًا بالحقول نفسها التي يُطلقها كل ما يُكتب عبر الموقع — لذا لن تحتاج أبدًا إلى التمييز بين ردّ إنسان وردّ روبوت.