Webhooks

الـ 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 سوى المنشورات التي أنشأها تطبيقك؛ والمنشور المنشأ في الواجهة لا يطلقه.

اقرأ أيضًا

يقول الـ webhook متى تصرفت Sofia. ولتجعل Sofia تتصرف، استخدم Sofia API أو CLI sofia أو خادم MCP (تبويبا API وAgents)، أو تكاملات الجهات الخارجية.