انتقل إلى المحتوى
مستندات المطورينتجريبي

الـ 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 }:

message.status
{
  "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
    }
  }
}
message.replied
{
  "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-Typeapplication/json
User-AgentMawgood-Webhooks/1
Mawgood-Event-Idمعرّف الحدث id (evt_…).
Mawgood-Signaturet=<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>"، بمفتاح التوقيع الخاص بعنوانك. للتحقق من طلب:

  1. اقرأ جسم الطلب الخام قبل أي تحويل من JSON.
  2. افصل الترويسة إلى t وقيم v1 (قد تكون قيمتين، انظر أدناه).
  3. ارفض الطلب إذا كان t يبعد أكثر من 5 دقائق عن الآن (طلب مُعاد تشغيله).
  4. احسب 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.

في هذه الصفحة