Webhooks: توقيع HMAC، عمليات إعادة التسليم وأفضل الممارسات
كيفية استلام نتيجة النسخ عبر الويب هوك: توقيع HMAC-SHA256، الرؤوس X-VPT-Signature و X-VPT-Event، 6 محاولات إعادة تسليم مع تأخير تصاعدي.
بدلاً من الاستعلام المتكرر عن API لمعرفة ما إذا كان النسخ قد اكتمل، يمكنك توفير webhook_url في الطلب وسيرسل VoxScriber طلب POST إلى خادمك عند اكتمال المهمة — سواء بنجاح أو بخطأ. إنها الطريقة الموصى بها للتكامل: تستهلك عددًا أقل من الطلبات وتصل النتيجة في الوقت المناسب.
كيف يعمل
- ترسل الصوت مع
webhook_url(يجب أن يكونhttps). - عند اكتمال المعالجة، نرسل طلب POST إلى هذا الرابط مع النتيجة.
- يستجيب خادمك بحالة
2xxلتأكيد الاستلام.
كل عملية تسليم تحمل ترويستي تعريف:
| الترويسة | المحتوى |
|---|---|
X-VPT-Event | نوع الحدث (الاكتمال، الفشل، إلخ.) |
X-VPT-Signature | توقيع HMAC-SHA256 للتسليم |
تحقق دائمًا من التوقيع قبل الثقة في المحتوى: احسب HMAC-SHA256 للجسم المستلم وقارنه بقيمة الترويسة X-VPT-Signature. يجب تجاهل أي طلب بدون توقيع صالح — يمكن لأي شخص اكتشاف رابط نقطة النهاية الخاصة بك.
عمليات إعادة التسليم التلقائية
إذا كانت نقطة النهاية الخاصة بك غير متاحة أو بطيئة جدًا، فإننا نحاول مرة أخرى:
- مهلة المحاولة: 15 ثانية.
- الحد الأقصى للمحاولات: 6.
- الانتظار بين المحاولات (تأخير تصاعدي): 5 دقائق → 30 دقيقة → ساعتان → 6 ساعات → 24 ساعة.
جميع عمليات التسليم محفوظة لدينا، لذا يمكنك مراجعة السجل مع الدعم إذا ضاع شيء ما.
استجب للويب هوك فورًا برمز 200 وقم بمعالجة المحتوى بشكل غير متزامن (قائمة انتظار، مهمة). إذا استغرقت معالجتك أكثر من 15 ثانية، يُحتسب التسليم كفشل ويدخل في قائمة إعادة التسليم — وقد تستلم نفس الحدث مرتين. عالج الأحداث بطريقة تكافؤية (idempotent).
أنت دائمًا تحصل على نتيجة نهائية
المهام العالقة لا تختفي بصمت:
- المهمة في قائمة الانتظار إذا توقفت لأكثر من 10 دقائق يُعاد ترتيبها تلقائيًا.
- المهمة قيد المعالجة إذا تعطلت لأكثر من 60 دقيقة يتم وضع علامة فاشلة عليها — وتُطلق webhook خطأ إلى رابطك.
بمعنى آخر: لكل صوت يتم إرساله، يتلقى نظامك استدعاءً نهائيًا، سواء بالنجاح أو بالفشل.
الأسئلة الشائعة
خادمي كان غير متاح. هل فقدت النتيجة؟
غالبًا لا: هناك حتى 6 محاولات موزعة على مدار ~24 ساعة. إذا فشلت جميعها، يبقى سجل التسليمات محفوظًا — تواصل مع الدعم لإعادة المعالجة.
هل يمكنني استخدام رابط http (بدون TLS)؟
لا. لأسباب أمنية، نقبل فقط روابط https، دون عمليات إعادة توجيه، ويتم حظر العناوين الداخلية/الخاصة.
كيف أفرّق بين webhook ناجح وwebhook خطأ؟
من خلال الترويسة X-VPT-Event التي تحدد نوع الحدث، ومن خلال محتوى جسم التسليم.
بماذا يجب أن تستجيب نقطة النهاية الخاصة بي؟
أي حالة 2xx خلال 15 ثانية. الحالات الأخرى (أو انتهاء المهلة) تُحتسب كفشل وتؤدي إلى إعادة التسليم.
مقالات ذات صلة
لم يتم الحل؟ افتح تذكرة — فريقنا يرد بسرعة.