تخطَّ إلى المحتوى

واجهة الإشعارات

كل نقاط النهاية في هذه الصفحة تحتاج النطاق manage:notifications. القنوات المتاحة لك تعتمد على باقتك (notificationChannels في GET /v1/plan)، والقناة التي لا تشملها باقتك ترد بالرمز 403 مع entitlement: notification_channels. لتفهم كيف تعمل التنبيهات اقرأ الإشعارات، وللاطلاع على البيانات المرسلة اقرأ أحداث Webhooks.

{
"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"
}
الحقلالقيم
channelemail أو 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).
modeimmediate (الافتراضي) أو digest_hourly أو digest_daily.
languageen (الافتراضي) أو ar: لغة الرسالة.
attach_imageلـ Webhooks: يضمّن صورة الإعلان أيضًا داخل البيانات المرسلة، مرمّزة بـ base64.
enabledالقيمة false توقف الاشتراك مؤقتًا.
verified_atتبقى null حتى تُؤكَّد الوجهة. والاشتراك الذي لم يُؤكَّد لا يستقبل إلا رسالة التأكيد.

يمكن أن يكون للمؤسسة حتى 50 اشتراكًا.

GET /v1/notifications/subscriptions

يرجع {"subscriptions": [ ... ], "channels": ["email", "webhook"]}، وتضم channels القنوات المتاحة على الخادم.

POST /v1/notifications/subscriptions
Terminal window
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).

PATCH /v1/notifications/subscriptions/{id}

أيّ من label وdestination وevent_types وfilters وmode وlanguage وattach_image وenabled. إن غيّرت الوجهة فعليك تأكيدها من جديد. ولا يمكنك إعادة تفعيل اشتراك على قناة لم تعد باقتك تشملها.

DELETE /v1/notifications/subscriptions/{id}

الرد 204.

POST /v1/notifications/subscriptions/{id}/verify

يرسل رسالة التأكيد (بلا جسم). الرد 202:

{ "method": "link", "expires_at": "2026-10-28T10:00:00Z" }
  • البريد الإلكتروني (method: link): يصل إلى العنوان بريد تأكيد. عندما تفتح الرابط تظهر صفحة فيها زر التأكيد، وبالضغط عليه يتأكّد الاشتراك.
  • Webhook (method: code): يستقبل عنوانك حدث notify.verify، وفيه data.code، وهو رمز يُستخدم مرة واحدة (يبدأ بـ vc_). أعده إلينا هكذا:
POST /v1/notifications/subscriptions/{id}/confirm
Terminal window
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.

POST /v1/notifications/subscriptions/{id}/test

يضع رسالة notify.test في طابور الإرسال إلى اشتراك مؤكَّد. الرد 202 {"delivery_id": 991}. تابعها في سجل الإرسال.

POST /v1/notifications/subscriptions/{id}/rotate-secret

يضيف سرّ توقيع جديدًا ويرجعه مرة واحدة فقط:

{ "secrets": { "secret": "whsec_NEW_SECRET" }, "note": "both the new and the previous secret sign deliveries until you call retire-secrets" }
POST /v1/notifications/subscriptions/{id}/retire-secrets

يُبقي أحدث سرّ فقط. الرد 204. اقرأ تجديد الأسرار.

GET /v1/notifications/deliveries
الاستعلاممعناه
statusqueued أو 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 توقفت عن المحاولة (اقرأ إعادة المحاولة).

GET /v1/notifications/deliveries/{id}/attempts

كل محاولة: attempt، وstarted_at، وduration_ms، وoutcome (ok أو transient أو permanent أو delayed)، وstatus_code، وresponse (مقتطع)، وerror.

POST /v1/notifications/deliveries/{id}/redeliver

يعيد وضع عملية تسليم منتهية (delivered أو dead أو skipped) في الطابور بمعرّف التسليم نفسه، كي يتمكن مستقبِلك من التعرّف على التكرار وتجاهله. الرد 202 {"delivery_id": 991, "status": "queued"}، أو 404 إن كانت ما تزال في الطابور.