الـ Webhooks
استقبل كل تغيير في الحالة وكل رد لحظة حدوثه، وتحقق من أنه قادم من موجود.
بدلًا من أن تسأل موجود عن التحديثات، أعطه عنوانًا وهو يخبرك. لكل مساحة عمل عنوان webhook واحد (رابط HTTPS عام)، يضبطه المالكون والمديرون من موجود › الإعدادات › للمطورين مع الأحداث التي يريدها ومفتاح التوقيع الخاص به.
تصل الأحداث عن كل حملات مساحة العمل، سواء أُنشئت من الواجهة البرمجية أو من لوحة التحكم، ويفرّق
بينها source (api أو dashboard).
الأحداث
type | متى |
|---|---|
message.status | دخلت رسالة الطابور، أو أُرسلت، أو وصلت، أو قُرئت، أو فشلت، أو تم تخطيها، أو أُلغيت. |
message.replied | رد أحد المستلمين (أول رد)، وتستمر المحادثة في صندوق الوارد. |
campaign.started | بدأ إرسال الحملة، ومنها الحملات التي وافق عليها فريق موجود. |
campaign.rejected | لم يوافق فريق موجود على الحملة، وdata.reviewNote يوضح السبب. |
campaign.completed | كل رسائل الحملة أُرسلت أو تم تخطيها. |
campaign.paused | توقفت الحملة مؤقتًا، وdata.pauseReason يوضح السبب. |
campaign.failed | تعذر تشغيل الحملة، أو فشلت كل رسائلها. |
campaign.cancelled | أُلغيت الحملة، والرسائل التي لم تُرسل بعد تصبح cancelled أولًا. |
ping | حدث التجربة من زر «ابعت حدث تجربة». يُرسل دائمًا، أيًا كانت الأحداث المختارة. |
كل حدث هو طلب POST بجسم JSON بالشكل { id, type, createdAt, data }:
{
"id": "evt_4Rt9Kp",
"type": "message.status",
"createdAt": "2026-11-20T10:15:04Z",
"data": {
"campaignId": "cmp_9Xa4Lr",
"campaignName": "Order updates",
"source": "api",
"at": "2026-11-20T10:15:03Z",
"recipient": {
"phone": "+201001234567",
"externalId": "order-1042",
"name": "Mona",
"status": "delivered",
"error": null,
"skipReason": null,
"sentAt": "2026-11-20T10:15:01Z",
"deliveredAt": "2026-11-20T10:15:03Z",
"readAt": null,
"repliedAt": null
}
}
}{
"id": "evt_7Hc2Wq",
"type": "message.replied",
"createdAt": "2026-11-20T10:20:11Z",
"data": {
"campaignId": "cmp_9Xa4Lr",
"phone": "+201001234567",
"externalId": "order-1042",
"repliedAt": "2026-11-20T10:20:11Z"
}
}recipient هو الكائن نفسه الذي يعيده GET /campaigns/{id}/recipients. ونص الرد لا يُرسل أبدًا:
اقرأه في صندوق الوارد في موجود. وتحمل أحداث campaign.* الحملة كما يعيدها GET /campaigns/{id} في
تلك اللحظة (status وpauseReason وreviewNote وcounts…)، ويحمل ping القيمة
{ "message": "Test event from Mawgood" }. وتجد كل الأشكال في مرجع الـ API.
الترويسات
| الترويسة | القيمة |
|---|---|
Content-Type | application/json |
User-Agent | Mawgood-Webhooks/1 |
Mawgood-Event-Id | معرّف الحدث id (evt_…). |
Mawgood-Signature | t=<unix seconds>,v1=<hex>. راجع أدناه. |
الرد وإعادة الإرسال
أعد أي استجابة 2xx خلال 10 ثوانٍ، ثم نفّذ عملك: ضع الحدث في طابور، أو عالجه بعد الرد. أي
استجابة أخرى (4xx أو 5xx أو انتهاء المهلة أو إعادة توجيه) تُعد فشلًا، ويعاد الإرسال بعد نحو
دقيقة، ثم 5 دقائق، ثم 30 دقيقة، ثم ساعتين، ثم 6 ساعات، ثم 12 ساعة، ثم مرة أخيرة عندما يبلغ عمر الحدث
24 ساعة. بعدها يصبح failed.
التسليم مرة واحدة على الأقل، وقد تصل الأحداث بأي ترتيب:
- تجاهل المكرر حسب
id(وهو أيضًا فيMawgood-Event-Id). قد يصل الحدث نفسه أكثر من مرة. احفظ المعرّفات التي عالجتها وتخطَّ المكرر. - توقع أي ترتيب. قد يصل
readقبلdeliveredالخاص به. قارنcreatedAt(وتوقيتات المستلم) بما لديك، ولا تُرجع الحالة إلى الخلف أبدًا. - قد تُرسل الحملة
campaign.completedثمcampaign.failed(عندما يرفض واتساب كل الرسائل بعد تسليم آخرها). اعتبر آخر حدثcampaign.*حسبcreatedAtهو حالة الحملة.
إذا ظل عنوانك يفشل (50 فشلًا متتاليًا على مدى أكثر من يوم)، يوقفه موجود، ويجعل أحداثه المنتظرة
failed، ويُبلغ مالكي مساحة العمل. أصلحه ثم شغّله مرة أخرى من الإعدادات › للمطورين.
سجل الإرسال
في الإعدادات › للمطورين › الويب هوك تجد كل أحداث آخر 30 يومًا بحالتها (pending أو delivered
أو failed)، وعدد المحاولات، وآخر رد، والـ JSON المرسل بالضبط. ومن هناك يعيد «ابعت تاني» إرسال
حدث فاشل (بالمعرّف والمحتوى نفسيهما وتوقيع جديد)، ويرسل «ابعت حدث تجربة» حدث ping. ويعمل
الزران حتى والعنوان متوقف.
والسجل نفسه متاح في الواجهة البرمجية بمفتاح له صلاحية webhooks:manage:
curl "https://api.mawgood.ai/v1/webhooks/deliveries?status=failed" \
-H "Authorization: Bearer $MAWGOOD_API_KEY"ويرد بـ { "data": [...], "nextCursor": null }، الأحدث أولًا (limit حتى 100).
التحقق من التوقيع
كل طلب يحمل ترويسة Mawgood-Signature:
Mawgood-Signature: t=1763633704,v1=5f2b9c…قيمة v1 هي HMAC-SHA256 بصيغة hex للنص "<t>.<raw body>"، بمفتاح التوقيع الخاص بعنوانك. للتحقق
من طلب:
- اقرأ جسم الطلب الخام قبل أي تحويل من JSON.
- افصل الترويسة إلى
tوقيمv1(قد تكون قيمتين، انظر أدناه). - ارفض الطلب إذا كان
tيبعد أكثر من 5 دقائق عن الآن (طلب مُعاد تشغيله). - احسب HMAC للنص
t + "." + rawBodyوقارنه بكلv1مقارنة ثابتة الزمن. اقبل الطلب إذا تطابق أحدها.
import crypto from 'node:crypto';
import express from 'express';
const app = express();
const SECRET = process.env.MAWGOOD_WEBHOOK_SECRET;
function verify(rawBody, header) {
let t = 0;
const signatures = [];
for (const part of header.split(',')) {
const [key, value = ''] = part.trim().split('=');
if (key === 't') t = Number(value);
if (key === 'v1' && value) signatures.push(value);
}
if (!t || signatures.length === 0) return false;
if (Math.abs(Date.now() / 1000 - t) > 300) return false; // older than 5 minutes
const expected = Buffer.from(
crypto.createHmac('sha256', SECRET).update(`${t}.${rawBody}`).digest('hex'),
);
// After a secret rotation, a request can carry two v1 signatures: accept either.
return signatures.some((sig) => {
const given = Buffer.from(sig);
return given.length === expected.length && crypto.timingSafeEqual(given, expected);
});
}
// express.raw keeps the body as bytes, exactly as Mawgood signed it.
app.post('/webhooks/mawgood', express.raw({ type: 'application/json' }), (req, res) => {
if (!verify(req.body.toString('utf8'), req.get('Mawgood-Signature') ?? '')) {
return res.sendStatus(400);
}
const event = JSON.parse(req.body);
res.sendStatus(200); // acknowledge first, then process
handle(event);
});استخدم الجسم الخام
تحويل JSON ثم إعادة كتابته يغير المسافات وترتيب المفاتيح، فلن يتطابق التوقيع. تحقق من البايتات كما وصلتك.
تغيير مفتاح التوقيع
يمكنك تغيير مفتاح التوقيع من الإعدادات › للمطورين. يبقى المفتاح القديم صالحًا 24 ساعة حتى
تحدّث خادمك. وخلال هذه المدة قد يحمل الطلب توقيعين v1، واحدًا لكل مفتاح:
Mawgood-Signature: t=1763633704,v1=5f2b9c…,v1=a81d07…تحقق بأي منهما. الأمثلة أعلاه تقبل الطلب إذا تطابق أي v1.