التوثيق / مرجع الواجهة البرمجية
Webhooks
استقبل أحداثاً موقّعة عند وصول الرسائل أو تغير حالتها أو تسليم محادثة.
في لوحة التحكم افتح المطورون ثم Webhooks وأضف رابط https واختر الأحداث. يعرض رد سر التوقيع مرة واحدة. استخدمه للتحقق من كل طلب.
#الأحداث
| الحدث | يُرسل عندما |
|---|---|
message.received | تصل رسالة من عميل. |
message.status | تصبح رسالة صادرة مرسلة أو مُسلَّمة أو مقروءة أو فاشلة. |
conversation.handover | تُسلَّم محادثة إلى موظف أو تُستعاد منه. |
#الحمولة
{
"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?"
}
}{ "id": "…", "event": "message.status", "created": "…",
"data": { "waMessageId": "wamid.HBg…", "status": "delivered", "error": null } }{ "id": "…", "event": "conversation.handover", "created": "…",
"data": { "conversationId": "b2d9…", "handler": "human", "reason": "agent_action" } }#الترويسات
| الترويسة | القيمة |
|---|---|
X-Radd-Event | اسم الحدث. |
X-Radd-Delivery | معرّف تسليم فريد. استخدمه لتجاهل التكرار. |
X-Radd-Timestamp | ثواني يونكس وقت التوقيع. |
X-Radd-Signature | sha256= متبوعة بـ 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.