دليل webhooks واتساب: الأحداث والأمان وإعادة المحاولة

{
  "messageId": "2603121407537573731",
  "channel": "SMS",
  "destination": "447700900123",
  "status": "DELIVERED",
  "timestamp": "2026-10-10T09:15:42Z",
  "reason": null
}

كيف أكتب معالجًا موثوقًا؟

افعل ثلاثة أشياء بالترتيب: خزّن الحدث الخام، ثم أكّد بـ 2xx، ثم عالج بصورة غير متزامنة. يتبع المعالج أدناه النمط الوارد في وثائقنا.

import express from "express";

const app = express();

// التقط الجسم الخام لتخزنه كما وصل تمامًا.
app.post(
  "/webhooks/omnichannels",
  express.json({ verify: (req, _res, buf) => { req.rawBody = buf.toString("utf8"); } }),
  async (req, res) => {
    try {
      await db.webhookEvents.insert({ receivedAt: new Date(), body: req.rawBody });
    } catch (err) {
      return res.sendStatus(500); // فشل التخزين: دع الحدث يُعاد إرساله
    }
    res.sendStatus(200);          // أكّد الاستلام بسرعة
    queue.publish("status-events", req.body); // أنجز العمل الفعلي في مكان آخر
  },
);

// العامل: معالجة idempotent
async function processEvent(event) {
  const id = event.messageId ?? event.message_id ?? event.id; // اربط بحسب القناة
  const status = event.status;
  const rank = { SUBMITTED: 1, SENT: 2, DELIVERED: 3, READ: 4, FAILED: 4, REJECTED: 4 };

  const current = await db.messages.findOne({ providerId: id });
  if (!current) return; // رسالة غير معروفة: سجّلها وافحصها
  if ((rank[status] ?? 0) <= (rank[current.status] ?? 0)) return; // مكرر أو قديم

  await db.messages.update({ providerId: id }, { status, updatedAt: new Date() });
}

from datetime import datetime, timezone
from flask import Flask, request

app = Flask(__name__)
RANK = {"SUBMITTED": 1, "SENT": 2, "DELIVERED": 3, "READ": 4, "FAILED": 4, "REJECTED": 4}

@app.post("/webhooks/omnichannels")
def omnichannels_webhook():
    raw = request.get_data(as_text=True)
    try:
        db.webhook_events.insert({"received_at": datetime.now(timezone.utc), "body": raw})
    except Exception:
        return "", 500           # فشل التخزين: دع الحدث يُعاد إرساله
    queue.publish("status-events", raw)  # عالج بصورة غير متزامنة
    return "", 200               # أكّد الاستلام بسرعة

الكائنان db وqueue هما تخزينك وطابور مهامك. وخريطة rank هي ما يجعل المعالجة idempotent: الحدث المكرر أو القديم لا يمثل تقدمًا فيُتجاهل.

قواعد المعالج الموثوق

• ردّ خلال ثوانٍ قليلة. لا تنفذ عملًا ثقيلًا قبل الرد.
• أعد 2xx فقط بعد تخزين الحدث. وإذا فشل التخزين فأعد 5xx.
• أزل التكرار بمعرّف الرسالة. قد تصل الحالة نفسها أكثر من مرة.
• لا تعد إرسال رسالة من المعالج أبدًا. قرر إعادة المحاولة في مهمة منفصلة، بعد فحص الحالة.
• احتفظ بالجسم الخام لاستكشاف الأخطاء ولإعادة تشغيل الأحداث بعد الإصلاح.

كيف أؤمّن webhook واتساب؟

يعتمد ذلك على من يرسل إلى نقطة نهايتك. توقّع Meta الـ webhooks التي ترسلها إلى التطبيقات التي تسجلها لديها. أما مواصفة واجهة OmniChannels.ai فلا تحدد ترويسة توقيع للـ webhook، فلا تنتظر واحدة.

بالنسبة لمخطط Meta، تقول وثائق Meta أن تولّد تجزئة HMAC-SHA256 من حمولة JSON بسر تطبيقك وتقارنها بالقيمة التي تلي sha256= في ترويسة X-Hub-Signature-256. ويُعرَّف HMAC نفسه في RFC 2104. احسبه على البايتات الخام لا على كائن أُعيد تسلسله، وقارن بزمن ثابت.

بالنسبة لنقطة نهايتنا:

• استخدم HTTPS فقط، بشهادة صالحة.
• استخدم مسارًا طويلًا يصعب تخمينه، وغيّره إذا تسرب.
• تحقق من شكل الجسم وارفض أي شيء غير متوقع.
• عامل الأحداث على أنها إشعارات. وقبل أي إجراء لا رجعة فيه، كاسترداد أو قفل احتيال، أكّد الحالة باستدعاء استعلام.

ماذا يحدث عند فشل التسليم؟

تعتمد إعادة المحاولة على المرسل. تقول وثائق Meta إنها تعيد محاولة التسليم الفاشل بتكرار متناقص حتى 7 أيام، وهذا قد ينتج إشعارات مكررة. وهذا سبب لتكون idempotent حتى لو نادرًا ما ترى التكرار. وبالنسبة لأحداث منصتنا، أكّد سلوك إعادة المحاولة مع مهندس الإعداد بدل افتراض أنه يطابق Meta.

وفي الحالتين، ابنِ للفقدان كما للتكرار: قد تتوقف نقطة نهايتك أثناء نشر، وقد تُسقط قاعدة في جدار الحماية الطلبات بصمت.

كيف أسترد الأحداث المفقودة؟

استعلم عن الدفعة، ولا تعد إرسال الرسالة.

curl "https://api.broadnet.me/whatsapp/message/bulk-insights?batch_Id=2609091405000000001&page=0&size=100" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

batch_Id هو المعرّف العائد من استدعاء الإرسال، وpage يبدأ من الصفر. شغّل مطابقة ليلية تقرأ دفعات اليوم السابق وتملأ أي فجوات.

قائمة استكشاف الأخطاء

1. هل العنوان مضبوط على الحساب أو الحساب الفرعي الصحيح؟
2. هل نقطة النهاية متاحة عبر HTTPS بشهادة صالحة؟
3. هل تردّ بـ 2xx بسرعة، أم تنتهي مهلتها؟
4. هل تحجب قاعدة جدار حماية أو WAF الطلبات؟
5. هل تسجّل الجسم الخام قبل التحليل، كي لا يخفي خطأ المحلل الحدث؟

مثال تطبيقي: مسار إشعارات لمتجر تجزئة

ترسل «سوق رفيق» (اسم افتراضي)، وهي متجر تجزئة في الإمارات، تحديثات الطلبات عبر واتساب وتريد حالة دقيقة في أداة الطلبات لديها.

1. تُرسَل الطلبات بـ sendbulk، ويُخزَّن batchId على الطلب. راجع إرسال رسالة واتساب عبر API.
2. تكتب نقطة نهاية الـ webhook كل حدث في جدول، ثم تعيد 200.
3. يرتّب عامل الحالات ويحدّث حالة رسالة الطلب.
4. تنشئ أحداث FAILED مهمة للدعم مع السبب، ويُنظر في بديل SMS وفق البديل بين القنوات.
5. تُوجَّه رسائل العملاء الواردة إلى صندوق الوارد المشترك ليرد الموظفون داخل النافذة.
6. تستدعي مهمة ليلية bulk-insights لدفعات الأمس وتصحح ما فات.

ما الأخطاء الشائعة؟

• عمل ثقيل قبل الرد، مما يسبب انتهاء المهلة وتسليمات متكررة.
• التأكيد قبل التخزين، مما يضيّع الأحداث عند فشل التخزين.
• الوثوق بالترتيب. SENT متأخرة تستبدل DELIVERED.
• البرمجة على الحمولة التوضيحية بدل الأحداث الحقيقية.
• إعادة تسلسل JSON قبل فحص التوقيع، مما يغيّر البايتات.
• إعادة الإرسال من المعالج، مما قد يسبب حلقة.
• الحدود: يصف هذا الدليل السلوك الموثّق لدينا. ينبغي تأكيد سياسة إعادة المحاولة وحقول الحمولة لحسابك أثناء الإعداد.

كيف تساعدك OmniChannels.ai؟

تدفع OmniChannels.ai حالات التسليم والرسائل الواردة لواتساب وSMS وRCS وقنوات أخرى إلى webhook الخاص بك بصيغة موحدة واحدة، مع webhooks منفصلة لكل حساب فرعي للموزّعين. وBroadNet مزوّد حلول أعمال رسمي لدى Meta، فتُعالَج متطلبات webhooks لدى Meta نيابةً عنك، وتتعامل أنت مع واجهتنا. اقرأ مرجع webhooks ووثائق واتساب API، أو شاهد كيف تظهر الأحداث في صندوق الوارد المشترك.