---
title: "دليل webhooks واتساب: الأحداث والأمان وإعادة المحاولة"
description: "كيف تعمل webhooks واتساب: أحداث الرسائل والحالات، ومعالج موثوق، والتحقق من توقيع Meta، وإعادة المحاولة، وعدم التكرار، والاسترداد عند فقدان الأحداث."
canonical: "https://omnichannels.ai/ar/blog/whatsapp-webhooks-guide/"
language: "ar"
updated: "2026-10-16"
publisher: "BroadNet Technologies"
brand: "OmniChannels.ai"
category: "integration"
primaryQuery: "whatsapp webhook"
keywords: ["webhook واتساب للأعمال API", "أحداث حالة رسائل واتساب webhook", "ترويسة X-Hub-Signature-256 في واتساب", "إعادة محاولة webhook واتساب", "webhook حالة تسليم واتساب", "معالج webhook بلا تكرار idempotent", "webhook الرسائل الواردة في واتساب"]
published: "2026-10-16"
author: "OmniChannels.ai Editorial Team"
reviewer: "BroadNet Messaging Solutions Team"
readingMinutes: 10
answer: "webhook واتساب نقطة نهاية HTTPS على خادمك تستقبل الأحداث: حالات التسليم للرسائل التي أرسلتها والرسائل التي يرسلها إليك العملاء. مع OmniChannels.ai تصل الحالات بصيغة SUBMITTED أو SENT أو DELIVERED أو READ أو FAILED أو REJECTED. خزّن الجسم الخام، وردّ بـ 2xx بسرعة، وأزل التكرار بمعرّف الرسالة، وعالج بصورة غير متزامنة. توقّع Meta webhooks الخاصة بها؛ ولا تحدد وثائقنا ترويسة توقيع، لذا أمّن نقطة نهايتك على مستوى النقل والتطبيق."
takeaways: ["تدفع webhooks الحالات والرسائل الواردة إلى نقطة نهاية HTTPS لديك فلا تحتاج إلى الاستعلام الدوري؛ وتُوحَّد حالات واتساب إلى SUBMITTED وSENT وDELIVERED وREAD وFAILED وREJECTED.", "يفعل المعالج الموثوق ثلاثة أشياء بالترتيب: يخزّن الحدث الخام، ثم يعيد 2xx، ثم يعالج بصورة غير متزامنة ودون تكرار.", "قد تصل الحالات بترتيب مختلف أو مرتين، فرتّبها بحسب تقدمها ولا تدع SENT متأخرة تستبدل DELIVERED محفوظة.", "توقّع Meta الـ webhooks المرسلة إلى التطبيقات بترويسة X-Hub-Signature-256، لكن مواصفة واجهة OmniChannels.ai لا تحدد توقيعًا للـ webhook، لذا استخدم HTTPS ومسارًا يصعب تخمينه والتحقق من الجسم.", "إذا فاتتك أحداث فاقرأ حالة واتساب لكل دفعة من نقطة نهاية bulk-insights بدل إعادة إرسال الرسائل."]
faq: 
  - q: "ما webhook واتساب؟"
    a: "webhook واتساب عنوان URL على خادمك تستدعيه المنصة بطلب HTTP POST كلما حدث شيء، مثل تسليم رسالة أو قراءتها أو فشلها، أو إرسال عميل رسالة إليك. وهو يغني عن الاستعلام الدوري. تعرض نقطة نهاية HTTPS وتشاركها مع مزوّدك وتعالج أحداث JSON التي تتلقاها."
  - q: "كيف أتحقق من توقيع webhook واتساب؟"
    a: "بالنسبة لـ webhook ترسله Meta مباشرة إلى تطبيقك الخاص، تقول وثائق Meta أن تحسب HMAC-SHA256 للحمولة الخام بسر تطبيقك وتقارنه بترويسة X-Hub-Signature-256. أما webhook الخاص بـ OmniChannels.ai فلا تحدد مواصفة الـ API ترويسة توقيع، لذا اعتمد على HTTPS ومسار يصعب تخمينه والتحقق من الجسم."
  - q: "ماذا يحدث إذا كانت نقطة نهاية webhook متوقفة؟"
    a: "تقول وثائق Meta إنها تعيد محاولة عمليات التسليم الفاشلة بتكرار متناقص حتى 7 أيام، وهذا قد ينتج نسخًا مكررة. وبالنسبة لأحداث منصتنا، أكّد سلوك إعادة المحاولة مع مهندس الإعداد لديك، واستخدم نقطة نهاية bulk-insights لقراءة حالة واتساب لكل مستلم في دفعة. وفي SMS تعيد نقطة resendDlr دفع الإيصالات."
  - q: "كيف أتعامل مع أحداث webhook المكررة؟"
    a: "اجعل المعالجة idempotent. ابحث عن الرسالة بمعرّفها، وقارن رتبة الحالة الواردة بالمحفوظة، وتجاهل الأحداث التي لا تمثل تقدمًا. يجب أن يكون تطبيق الحدث نفسه مرتين بنفس أثر تطبيقه مرة. وخزّن الجسم الخام لكل حدث لتعيد تشغيله بعد إصلاح خلل."
  - q: "ما سرعة الاستجابة المطلوبة من نقطة نهايتي؟"
    a: "خلال ثوانٍ قليلة. خزّن الحدث الخام، وأعد 2xx، وأنجز العمل الفعلي في طابور أو عامل. لا تستدعِ خدمات أخرى أو ترسل رسائل أو تنفذ استعلامات ثقيلة قبل الرد. وإذا فشل التخزين فأعد 5xx ليتمكن المرسل من إعادة المحاولة، بدل تأكيد حدث ضاع منك."
  - q: "هل يمكنني استخدام webhook لإرسال رد تلقائيًا؟"
    a: "نعم، لكن ليس من داخل المعالج. أكّد الحدث، ثم قرر الرد في مهمة منفصلة. داخل نافذة خدمة العملاء البالغة 24 ساعة يمكنك إرسال رسالة حرة؛ وخارجها تحتاج قالبًا معتمدًا. ولا تعد إرسال رسالة من معالج الـ webhook نفسه أبدًا، لتجنب الحلقات والتكرار."
sources: 
  - title: "نظرة عامة على webhooks — منصة واتساب للأعمال، Meta for Developers"
    url: "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview"
  - title: "إنشاء نقطة نهاية webhook — منصة واتساب للأعمال، Meta for Developers"
    url: "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/create-webhook-endpoint"
  - title: "RFC 2104: HMAC: التجزئة المفتاحية لمصادقة الرسائل"
    url: "https://www.rfc-editor.org/rfc/rfc2104"
---

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

Canonical: https://omnichannels.ai/ar/blog/whatsapp-webhooks-guide/
Language: ar
Publisher: OmniChannels.ai by BroadNet Technologies

هذا الدليل موجّه للمهندسين الذين يحتاجون إلى استقبال أحداث واتساب بصورة موثوقة: حالات التسليم للرسائل التي يرسلونها والرسائل الواردة من العملاء. يشرح كيف تعمل webhooks، وما ينبغي بناؤه في المعالج، وكيف يختلف الأمان بين webhooks لدى Meta وwebhooks لدينا، وما العمل حين تفقد الأحداث.

## ما webhooks واتساب ولماذا نستخدمها؟

webhooks واتساب استدعاءات HTTP عكسية. حين تتغير حالة رسالة أو يكتب لك عميل، ترسل المنصة طلب `POST` بجسم JSON إلى نقطة نهايتك. لا تحتاج إلى الاستعلام الدوري، وترى الأحداث لحظة وقوعها.

عائلتان من الأحداث تهمّان:

- **أحداث الحالة** للرسائل التي أرسلتها: في الطابور ومُرسلة ومُسلَّمة ومقروءة وفاشلة.
- **الرسائل الواردة** من العملاء، التي تفتح نافذة خدمة العملاء البالغة 24 ساعة أو تمدّدها. راجع [دليل النافذة](/ar/blog/whatsapp-24-hour-customer-service-window/).

لا يخبرك استدعاء الإرسال إلا أن الرسائل وُضعت في الطابور. أما الـ webhook فهو المكان الذي تعرف فيه ما حدث لكل مستلم.

## أي أحداث وحالات سأتلقى؟

في OmniChannels.ai تُبلغ كل قناة بالحالات الموحدة نفسها، لذا يمكن لمعالج واحد أن يخدم واتساب وSMS وغيرهما.

| الحالة | المعنى | نهائية؟ |
|---|---|---|
| `SUBMITTED` | قبلتها المنصة ووُضعت في الطابور | لا |
| `SENT` | سُلّمت إلى القناة | لا |
| `DELIVERED` | تأكد وصولها إلى جهاز المستلم | عادةً؛ وقد تتبعها `READ` |
| `READ` | فتحها المستلم، حيث تبلّغ القناة عن القراءة | نعم |
| `FAILED` | لم تُسلَّم؛ ويحمل الحدث سببًا حيث يتوفر | نعم |
| `REJECTED` | رُفضت، مثل محتوى محظور أو مرسل غير مسجل | نعم |

تعامل مع الحالات على أنها تقدم قد يصل بترتيب مختلف، وتوقّع قيمًا جديدة بمرور الوقت. لا تجعل معالجك يفشل عند حالة لا تعرفها. راجع [حالات تسليم الرسائل موضّحة](/ar/blog/message-delivery-status-explained/).

## كيف أعدّ نقطة النهاية؟

اعرض نقطة نهاية HTTPS، وأعطِ العنوان لمزوّدك، ثم اختبر برقمك الخاص.

1. أنشئ نقطة نهاية تقبل `POST` بجسم JSON، مثل `https://api.example.com/webhooks/omnichannels`.
2. أرسل العنوان إلى فريقنا أو مدير حسابك ليضبطه على حسابك. ويمكن للموزّعين الحصول على webhook منفصل لكل حساب فرعي.
3. أرسل رسالة اختبار إلى رقمك وتأكد أن الأحداث تصل.

أثناء التطوير، يمنح نفق مثل ngrok خادمك المحلي عنوان HTTPS عامًا. وإذا ربطت أيضًا تطبيقًا مباشرة بـ Meta، فالتحقق من نقطة النهاية لدى Meta خطوة منفصلة: طلب `GET` يحمل رمز تحقق وقيمة `hub.challenge`، وتردّ عليه بـ `200` مع قيمة التحدي، كما في [وثائق نقطة نهاية webhook](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/create-webhook-endpoint) لدى Meta.

## كيف تبدو الحمولة؟

تختلف بحسب القناة. لا تحدد مواصفة الـ API مخطط webhook واحدًا، لذا سجّل الجسم الخام أولًا وابنِ الربط بين الحقول التي تحتاجها من أحداث حقيقية على حسابك. يعرض المثال نوع المعلومات التي يحملها حدث التسليم وهو توضيحي فقط.

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

لا تبرمج على أسماء الحقول هذه دون فحص حدث حقيقي. اطلب من مهندس الإعداد لديك حمولات نموذجية لكل قناة واحتفظ بها مثبتات اختبار. وللوثائق الأوسع راجع [مرجع webhooks](/developers/webhooks/).

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

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

```js
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() });
}
```

```python
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 إلى تطبيقك الخاص | OmniChannels.ai إلى نقطة نهايتك |
|---|---|---|
| التوقيع | ترويسة `X-Hub-Signature-256`، وفق وثائق Meta | لا شيء محدد في مواصفة الـ API |
| التحقق | HMAC-SHA256 للحمولة الخام بسر تطبيقك، يُقارن بالترويسة | لا ينطبق |
| ضوابطك | افحص التوقيع في كل `POST` | HTTPS بشهادة صالحة، ومسار يصعب تخمينه، وتحقق صارم من الجسم |

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

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

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

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

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

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

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

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

| الحاجة | الاستدعاء | ملاحظات |
|---|---|---|
| قراءة حالة واتساب لكل مستلم | `GET /whatsapp/message/bulk-insights` | رشّح دفعة بـ `status` أو `destination`؛ مع ترقيم صفحات بـ `page` و`size` |
| إعادة دفع إيصالات تسليم SMS | `POST /sms/resendDlr` | رشّح بـ `startDate` و`endDate` و`senderId` و`messageStatus` |

```bash
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](/ar/blog/send-whatsapp-message-api-examples/).
2. تكتب نقطة نهاية الـ webhook كل حدث في جدول، ثم تعيد `200`.
3. يرتّب عامل الحالات ويحدّث حالة رسالة الطلب.
4. تنشئ أحداث `FAILED` مهمة للدعم مع السبب، ويُنظر في بديل SMS وفق [البديل بين القنوات](/ar/blog/channel-fallback-strategy/).
5. تُوجَّه رسائل العملاء الواردة إلى صندوق الوارد المشترك ليرد الموظفون داخل النافذة.
6. تستدعي مهمة ليلية `bulk-insights` لدفعات الأمس وتصحح ما فات.

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

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

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

تدفع OmniChannels.ai حالات التسليم والرسائل الواردة لواتساب وSMS وRCS وقنوات أخرى إلى webhook الخاص بك بصيغة موحدة واحدة، مع webhooks منفصلة لكل حساب فرعي للموزّعين. وBroadNet مزوّد حلول أعمال رسمي لدى Meta، فتُعالَج متطلبات webhooks لدى Meta نيابةً عنك، وتتعامل أنت مع واجهتنا. اقرأ [مرجع webhooks](/developers/webhooks/) و[وثائق واتساب API](/developers/whatsapp/)، أو شاهد كيف تظهر الأحداث في [صندوق الوارد المشترك](/ar/platform/unified-inbox/).