واجهة الإشعارات
كل نقاط النهاية في هذه الصفحة تحتاج النطاق manage:notifications. القنوات المتاحة لك تعتمد على باقتك
(notificationChannels في GET /v1/plan)، والقناة التي لا تشملها باقتك ترد بالرمز 403 مع
entitlement: notification_channels. لتفهم كيف تعمل التنبيهات اقرأ الإشعارات، وللاطلاع على
البيانات المرسلة اقرأ أحداث Webhooks.
كائن الاشتراك
Section titled “كائن الاشتراك”{ "id": 4, "label": "Ops webhook", "channel": "webhook", "destination": { "url": "https://hooks.example.com/ad80", "secrets": [{ "id": "s_a1b2c3d4", "created_at": "2026-10-26T10:00:00Z" }] }, "event_types": ["creative.violation"], "filters": { "app_ids": ["com.example.news"], "rule_ids": ["no-alcohol"], "min_score": 0.7 }, "mode": "immediate", "language": "en", "attach_image": false, "enabled": true, "verified_at": "2026-10-26T10:02:11Z", "created_by": "user:31", "created_at": "2026-10-26T10:00:00Z", "updated_at": "2026-10-26T10:02:11Z"}| الحقل | القيم |
|---|---|
channel | email أو webhook. |
destination | للبريد الإلكتروني: {"to": "alerts@example.com"}. لـ Webhook: {"url": "https://..."}؛ ولا تظهر الأسرار أبدًا، بل معرّفاتها وتواريخها فقط. |
event_types | واحد على الأقل من creative.violation وcreative.classified وkey.expiring. |
filters | اختياري. app_ids وrule_ids (حتى 100 لكل منهما، والقائمة الفارغة تعني الكل)، وmin_score (من 0 إلى 1). |
mode | immediate (الافتراضي) أو digest_hourly أو digest_daily. |
language | en (الافتراضي) أو ar: لغة الرسالة. |
attach_image | لـ Webhooks: يضمّن صورة الإعلان أيضًا داخل البيانات المرسلة، مرمّزة بـ base64. |
enabled | القيمة false توقف الاشتراك مؤقتًا. |
verified_at | تبقى null حتى تُؤكَّد الوجهة. والاشتراك الذي لم يُؤكَّد لا يستقبل إلا رسالة التأكيد. |
يمكن أن يكون للمؤسسة حتى 50 اشتراكًا.
عرض الاشتراكات
Section titled “عرض الاشتراكات”يرجع {"subscriptions": [ ... ], "channels": ["email", "webhook"]}، وتضم channels القنوات المتاحة على الخادم.
إنشاء اشتراك
Section titled “إنشاء اشتراك”curl -s -X POST https://api.ad80.dev/v1/notifications/subscriptions \ -H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \ -d '{ "label": "Ops webhook", "channel": "webhook", "destination": {"url": "https://hooks.example.com/ad80"}, "event_types": ["creative.violation"], "mode": "immediate", "language": "en" }'الرد 201:
{ "subscription": { "id": 4, "channel": "webhook", "verified_at": null, "...": "..." }, "secrets": { "secret": "whsec_YOUR_SIGNING_SECRET" }}في Webhook، secrets.secret هو سرّ التوقيع. لن تراه إلا في هذا الرد، فاحفظه لكي
تتحقق من التواقيع. يجب أن تكون عناوين Webhooks https، وأن تشير إلى
عناوين عامة؛ أما العناوين الخاصة، وعناوين loopback وlink-local، وعناوين خدمات metadata فمرفوضة (400).
التعديل أو الحذف
Section titled “التعديل أو الحذف”أيّ من label وdestination وevent_types وfilters وmode وlanguage وattach_image وenabled. إن غيّرت
الوجهة فعليك تأكيدها من جديد. ولا يمكنك إعادة تفعيل اشتراك على قناة لم تعد باقتك تشملها.
الرد 204.
تأكيد وجهة
Section titled “تأكيد وجهة”يرسل رسالة التأكيد (بلا جسم). الرد 202:
{ "method": "link", "expires_at": "2026-10-28T10:00:00Z" }- البريد الإلكتروني (
method: link): يصل إلى العنوان بريد تأكيد. عندما تفتح الرابط تظهر صفحة فيها زر التأكيد، وبالضغط عليه يتأكّد الاشتراك. - Webhook (
method: code): يستقبل عنوانك حدثnotify.verify، وفيهdata.code، وهو رمز يُستخدم مرة واحدة (يبدأ بـvc_). أعده إلينا هكذا:
curl -s -X POST https://api.ad80.dev/v1/notifications/subscriptions/4/confirm \ -H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \ -d '{"code": "vc_THE_CODE_YOU_RECEIVED"}'يرجع {"verified": true}. تنتهي صلاحية طلب التأكيد بعد 48 ساعة (expires_at)، وتستطيع أن تبدأه من جديد عند الحاجة.
وللتأكيد حدّ لعدد المحاولات: إن حاولت كثيرًا يصلك 429 مع Retry-After.
إرسال رسالة تجربة
Section titled “إرسال رسالة تجربة”يضع رسالة notify.test في طابور الإرسال إلى اشتراك مؤكَّد. الرد 202 {"delivery_id": 991}. تابعها في سجل
الإرسال.
تجديد سرّ Webhook
Section titled “تجديد سرّ Webhook”يضيف سرّ توقيع جديدًا ويرجعه مرة واحدة فقط:
{ "secrets": { "secret": "whsec_NEW_SECRET" }, "note": "both the new and the previous secret sign deliveries until you call retire-secrets" }يُبقي أحدث سرّ فقط. الرد 204. اقرأ تجديد الأسرار.
عمليات التسليم
Section titled “عمليات التسليم”| الاستعلام | معناه |
|---|---|
status | queued أو claimed أو delivered أو dead أو digest_pending أو digested أو skipped. |
subscription | معرّف اشتراك. |
limit | من 1 إلى 500، والافتراضي 100. |
{ "deliveries": [ { "id": 991, "event_id": 2, "event_type": "creative.violation", "subscription_id": 4, "status": "delivered", "attempts": 1, "next_attempt_at": "2026-10-26T14:03:00Z", "last_error": "", "created_at": "2026-10-26T14:03:00Z", "delivered_at": "2026-10-26T14:03:01Z", "delivery_mode": "immediate" } ]}قيمة delivery_mode هي immediate أو digest (اشتراك بنمط الملخص، أو تنبيه أُجّل إلى الملخص لأن رصيد الإشعارات
السريعة الشهري نفد). وتعني dead أن AD80 توقفت عن المحاولة (اقرأ إعادة المحاولة).
كل محاولة: attempt، وstarted_at، وduration_ms، وoutcome (ok أو transient أو permanent أو delayed)،
وstatus_code، وresponse (مقتطع)، وerror.
يعيد وضع عملية تسليم منتهية (delivered أو dead أو skipped) في الطابور بمعرّف التسليم نفسه، كي يتمكن
مستقبِلك من التعرّف على التكرار وتجاهله. الرد 202 {"delivery_id": 991, "status": "queued"}، أو 404 إن كانت ما
تزال في الطابور.