أرسل الإرسالات إلى Webhook وأعد محاولة ما فات مستقبلك

يرسل Webhook كل إرسال مقبول إلى رابط تملكه خلال ثوانٍ، فيمكن لعميل محتمل أن يصل إلى نظام CRM لديك أو إلى كودك الخاص دون أن ينتظر ملخّص بريد. وWebhooks جزء من FormFlow منذ v1.0.0. يضيف هذا الدليل وجهة، ويبيّن ما يتلقاه مستقبلك وكيف تتحقق منه، ثم يغطي الجزء الذي يهم يوم يتوقف مستقبلك: ما يعيد FormFlow محاولته بنفسه، وكيف تعيد إرسال الباقي بـ«إعادة محاولة التسليمات الفاشلة».

ما تحتاج إليه

مستقبل تتحكم به يقبل طلب POST بمتن JSON. ويجب أن يكون عنوانه https وألا يُحلّ إلا إلى عناوين عامة. ترفض اللوحة أي شيء آخر عند الحفظ، فلا يعمل عنوان localhost، والنفق هو الطريقة المعتادة للاختبار.

أضف الوجهة

1. افتح النموذج في اللوحة واذهب إلى تبويب «التسليم».

2. تحت «وجهات Webhook»، اضغط «إضافة وجهة».

3. اترك «الإرسال باسم» على «FormFlow JSON (موقَّع)». والخيار الآخر، «رسالة Slack»، يقبل رابط Webhook وارد من Slack.

4. الصق عنوان مستقبلك في «رابط الوجهة» واترك «جارٍ التسليم» مفعّلاً.

5. احفظ النموذج. يعرض إشعار بعنوان «انسخ أسرار توقيع Webhook الآن» الرابط والسرّ لكل وجهة جديدة. ويبقى على الشاشة حتى تغلقه، ويقول إن الأسرار لا تُعرض مرة أخرى. احفظ السرّ في مدير أسرارك. وللحصول على سرّ جديد، احذف الوجهة وأعد إضافتها.

6. اضغط «إرسال اختبار» في صف الوجهة. ستحصل على «تم تسليم الاختبار»، أو «فشل تسليم الاختبار» مع نص الخطأ الخاص بمستقبلك. يجب حفظ الصف أولاً، والزر محدود بـ 20 تسليم اختبار في الساعة.

ثم أرسل إرسالاً حقيقياً وافتحه في اللوحة. يسرد جدول «طلبات التسليم» فيه كل وجهة يُستحق لها ذلك الإرسال، بحالة «قيد الانتظار» أو «محجوز» أو «تم التسليم» أو «متوقّف»، وعدد المحاولات، و«معرّف التسليم»، وآخر خطأ.

ما يتلقاه مستقبلك

طلب POST واحد لكل إرسال ليس إزعاجاً. المتن مستند JSON صغير، وتصحبه ثلاث ترويسات. هذا هو الشكل، بقيم نائبة:

{
  "id": "SUBMISSION_UUID",
  "form": { "id": "FORM_UUID", "name": "Contact Us" },
  "submitted_at": "2026-10-08T09:00:00+00:00",
  "data": { "name": "Ada Lovelace", "email": "ada@example.com" }
}

• X-FormFlow-Timestamp هو وقت المحاولة، بالثواني.

• X-FormFlow-Signature-256 هو sha256= متبوعاً بـ HMAC-SHA256 للختم الزمني ونقطة والمتن الخام، بمفتاح هو سرّ الوجهة.

• X-FormFlow-Delivery-Id يحدّد هوية التسليم. ويبقى نفسه في كل إعادة محاولة.

تحقق من التوقيع قبل أن تثق بطلب، على المتن الخام لا على نسخة أُعيد ترميزها. هذه نسخة PHP، بالشكل الذي تعطيه به وثائق API في FormFlow:

function formflow_verify(string $rawBody, string $timestamp, string $signature, string $secret): bool
{
    if (abs(time() - (int) $timestamp) > 300) {
        return false;
    }

    $expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

    return hash_equals($expected, $signature);
}

ما يعيد FormFlow محاولته بنفسه

ينتظر FormFlow حتى 10 ثوانٍ للرد. وأي استجابة 2xx تُعدّ تسليماً. وتُعاد محاولة انتهاء المهلة، أو انقطاع الاتصال، أو 408 أو 429 أو استجابة 5xx، لما يصل إلى ست محاولات في المجموع، بانتظار 10 ثوانٍ ثم دقيقة ثم 5 دقائق ثم 30 دقيقة ثم ساعتين بينها. أما أي إجابة أخرى، بما في ذلك 3xx أو 4xx، فتُعامَل كرفض دائم ولا تُعاد محاولتها تلقائياً. ولا يتبع FormFlow عمليات التوجيه، فالوجهة التي تجيب بتوجيه تُعدّ فاشلة. وجّه الوجهة إلى عنوانها النهائي.

وإذا ظلت وجهة تطلب إعادة المحاولة ثم نفدت محاولاتها، يُطفئ FormFlow «جارٍ التسليم» لها ويُبلّغ مالكي الفريق بالبريد الإلكتروني. ويُعرض التسليم الذي نفدت محاولاته بحالة «متوقّف». وتظل لوحة التحكم أيضاً تعرض Webhook تمريره متوقف، مع سلسلة إخفاقاته، حتى ينجح تسليم.

أعد محاولة ما فات مستقبلك

قبل v1.33، كان كل إرسال فات يحتاج إلى «إعادة المحاولة الآن» خاصة به. والآن تغطي ضغطة واحدة وجهة بأكملها. والإصدار موجود في سجل التغييرات. والترتيب مهم:

1. أصلح المستقبل أولاً. يحصل كل تسليم فاشل على محاولة إضافية واحدة، فإعادة المحاولة ضد مستقبل لا يزال معطّلاً لن تفعل سوى أن تفشل مجدداً.

2. في تبويب «التسليم»، تحقق من مفتاح «جارٍ التسليم» للوجهة. إن أطفأه FormFlow، فشغّله واحفظ النموذج. إذ تُرفض إعادة محاولة وجهة مُطفأة بالرسالة "شغّل «جارٍ التسليم» واحفظ النموذج، ثم أعد المحاولة."

3. اضغط «إعادة محاولة التسليمات الفاشلة» في صف الوجهة وأكّد. تقول النافذة إن كل تسليم فاشل لا يزال إرساله ممكناً يُعاد وضعه في قائمة الانتظار، بمعرّف التسليم والحمولة الأصليين.

4. يخبرك إشعار كم منها أُعيد إلى قائمة الانتظار. وتضع الضغطة الواحدة 500 كحد أقصى. وإن بقي أكثر، يقول إنه ينبغي أن تضغط مجدداً.

5. افتح إرسالاً وتحقق من جدول «طلبات التسليم» فيه. لقد ارتفع عدد المحاولات وينبغي أن تصل الحالة إلى «تم التسليم».

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

حدود ينبغي أن تعرفها

• الوجهة الجديدة تستقبل فقط الإرسالات التي تصل بعد إعدادها. ولا تُرسَل إليها الإرسالات الموجودة لديك بالفعل.

• الإزعاج لا يُمرَّر.

• «إعادة محاولة التسليمات الفاشلة» تعيد إرسال التسليمات التي لا يزال إرسالها ممكناً فقط، وإلى الوجهة كما هي الآن فقط.

• التسليم مرة واحدة على الأقل. وعلى مستقبلك أن يتحمل التكرار.