التوثيق / مرجع الواجهة البرمجية

Webhooks

استقبل أحداثاً موقّعة عند وصول الرسائل أو تغير حالتها أو تسليم محادثة.

في لوحة التحكم افتح المطورون ثم Webhooks وأضف رابط https واختر الأحداث. يعرض رد سر التوقيع مرة واحدة. استخدمه للتحقق من كل طلب.

#الأحداث

الحدثيُرسل عندما
message.receivedتصل رسالة من عميل.
message.statusتصبح رسالة صادرة مرسلة أو مُسلَّمة أو مقروءة أو فاشلة.
conversation.handoverتُسلَّم محادثة إلى موظف أو تُستعاد منه.

#الحمولة

message.received
{
  "id": "2f0c…",
  "event": "message.received",
  "created": "2026-11-15T10:21:04.000Z",
  "data": {
    "waMessageId": "wamid.HBg…", "conversationId": "b2d9…",
    "customer": { "waId": "966501234567", "name": "Khalid" },
    "type": "text", "text": "Do you ship to Dammam?"
  }
}
message.status
{ "id": "…", "event": "message.status", "created": "…",
  "data": { "waMessageId": "wamid.HBg…", "status": "delivered", "error": null } }
conversation.handover
{ "id": "…", "event": "conversation.handover", "created": "…",
  "data": { "conversationId": "b2d9…", "handler": "human", "reason": "agent_action" } }

#الترويسات

الترويسةالقيمة
X-Radd-Eventاسم الحدث.
X-Radd-Deliveryمعرّف تسليم فريد. استخدمه لتجاهل التكرار.
X-Radd-Timestampثواني يونكس وقت التوقيع.
X-Radd-Signaturesha256= متبوعة بـ HMAC-SHA256 سداسي عشري لـ timestamp + "." + rawBody بسر التوقيع.

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

const crypto = require('crypto');
// rawBody = the exact request body string, secret = your whsec_… value
function isValid(headers, rawBody, secret) {
  const ts = headers['x-radd-timestamp'];
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;          // reject replays
  const a = Buffer.from(headers['x-radd-signature']), b = Buffer.from(expected);
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

#التسليم وإعادة المحاولة

  • أجب برمز 2xx خلال 8 ثوانٍ. يجب أن يكون رابطك عاماً وhttps.
  • عند الفشل يعيد رد المحاولة بعد دقيقة و5 دقائق و30 دقيقة وساعتين و6 ساعات ثم يسجّل الفشل. لا تُهمل التسليمات الفاشلة بصمت.
  • استخدم إرسال تجربة في صفحة المطورين لفحص رابطك. وتعرض قائمة التسليمات كل محاولة.
  • قد تتكرر الأحداث. اجعل معالجك آمناً للتكرار باستخدام X-Radd-Delivery.
Webhooks · توثيق رد