Webhooks
نبّه نظامًا آخر حين ينشر منشور Sofia أو يفشل: webhooks موقّعة تُسجَّل عبر API، مع إعادة المحاولة تلقائيًا عند الحاجة.
الـ webhook هو استدعاء HTTP تطلقه Sofia حين يُنشر منشور أو يفشل. استخدمه لنقل المحتوى إلى جدول بيانات، أو تنبيه أداة مراسلة، أو تشغيل سيناريو في Zapier أو n8n.
إضافة واحد
- 1. أعطه عنوانًا. عنوان https عام ترسل إليه Sofia الحدث.
- 2. اختر الأحداث.
post.publishedوpost.failed. - 3. سجّله.
POST /v1/webhooks: لا يظهر سرّ التوقيع (whsec_…) إلا في هذا الرد. - 4. أرسل اختبارًا.
POST /v1/webhooks/{id}/testيرسل حدثwebhook.test، موقّعًا مثل غيره.
الطلب الكامل مفصّل في تبويب API: تسجيل webhook. لا تُعلَن سوى المنشورات التي أنشأها تطبيقك.
بناء المستقبِل
أرسل دائمًا اختبارًا أولًا واحتفظ بالجسم المستلَم: إنه العقد، وأوثق من أي وصف. ترسل Sofia كل حدث بـ POST بصيغة JSON { id, type, createdAt, data }، مع الترويسات Sofia-Event-Id وSofia-Event-Type وSofia-Signature.
- تحقق من التوقيع. قيمة
Sofia-Signatureهيt=<unix time>,v1=<hex>، حيثv1هو HMAC-SHA256 للقيمة<t>.<raw body>بسرّك. احسبه على الجسم الخام وارفض ختمًا زمنيًا قديمًا. - أجب بـ `2xx` بسرعة، ثم أنجز العمل بعد ذلك: فنقطة الاستقبال البطيئة لا تتميّز عن نقطة معطلة.
- كن متماثل الأثر (idempotent). قد يصل الحدث نفسه مرتين: أزل التكرار بحسب
Sofia-Event-Id.
حين يتوقف webhook عن العمل
العنوان لا يمكن الوصول إليه
تستدعي Sofia من خوادمها: يجب أن يكون العنوان https عامًا. لا يُتَّبع تحويل أبدًا، و10 ثوانٍ دون رد تُحتسب فشلًا.
العنوان يعيد خطأ
أي رد غير 2xx يطلق محاولة جديدة بعد دقيقة، ثم 5 دقائق، ثم 30 دقيقة، ثم ساعتين، حتى 5 محاولات. انظر أولًا إلى سجلاتك أنت، ثم أعد الإنتاج بـ POST /v1/webhooks/{id}/test.
لم يُنشئ تطبيقك المنشور
لا يعلن الـ webhook سوى المنشورات التي أنشأها تطبيقك؛ والمنشور المنشأ في الواجهة لا يطلقه.