استقبال Webhook

تُستخدم إشعارات Webhook حاليًا بعد تسوية مهام الفيديو العادية ووصولها إلى حالة نهائية. لا تفترض أن الصور المتزامنة أو الصوت أو مساحات العمل الدائمة تدعم الاشتراكات نفسها. لا تتضمن الإشعارات نصوص التوجيه أو روابط النتائج أو أخطاء الخدمة الخام.

الإعداد والاشتراك

أنشئ نقطة استقبال HTTPS في Webhooks الحساب، واحفظ secret التوقيع المعروض مرة واحدة. تستخدم عمليات الإدارة جلسة تسجيل الدخول، لا API العامة بنظام Bearer؛ ويختلف secret عن API Key. عند طلب الفيديو أرسل webhook_endpoint_id مفعّلًا للحساب نفسه؛ لا تُقبل روابط استدعاء راجع عشوائية. هذا الحقل جزء من مدخلات عدم التكرار، ولا يجوز تبديل نقطة النهاية عند إعادة الطلب.

التحقق من التوقيع وإزالة التكرار

{"id":"evt_example","type":"video.succeeded","created_at":1790000000,"data":{"task_id":"vid_example","status":"succeeded"}}

أنواع الأحداث هي video.succeeded أو video.failed أو video.cancelled. احفظ بايتات الطلب الخام وتحقق من Webhook-Id وWebhook-Timestamp وWebhook-Signature. يأتي التوقيع بالشكل v1=<hex>، وتستخدم HMAC-SHA256 سلسلة secret كمفتاح. تتكون الرسالة من معرّف الحدث والطابع الزمني Unix بالثواني وbody الخام، مع فاصلَي سطر بينهما دون سطر نهائي:

import hashlib, hmac
message = event_id.encode() + b"\n" + timestamp.encode() + b"\n" + raw_body
expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
valid = hmac.compare_digest(received_hex, expected)

حدّد حجم الطلب، وارفض الترويسات المفقودة أو المكررة وإصدارات التوقيع غير المعروفة. تحقق من انحراف الساعة (يوصى بحد أقصى 5 دقائق)، ولا تحلل JSON إلا بعد نجاح التوقيع، وتأكد من تطابق id داخل body مع Webhook-Id. المثال يحسب مقارنة التوقيع فقط؛ وعلى المستقبِل إكمال الفحوص المذكورة.

احفظ الحدث بشكل دائم وموثوق أو أكمل معالجته بضمان عدم التكرار قبل الرد بـ 2xx. استخدم event ID الثابت لإزالة التكرار؛ يظل body والمعرّف ثابتين في المحاولات، بينما يتجدد الطابع الزمني والتوقيع. بعد الاستلام استعلم عن المهمة والنتيجة باستخدام Key الأصلي؛ الإشعار نفسه ليس تصريح تنزيل للنتيجة.

المحاولات وتدوير المفاتيح

تؤدي أخطاء الشبكة و408 و429 و5xx إلى محاولات تلقائية بفواصل متزايدة. تُعد 2xx فقط نجاحًا، ولا تُتبع إعادة التوجيه ولا تُعاد بقية 4xx تلقائيًا. الحد الأقصى 12 محاولة خلال 24 ساعة؛ بعدها افحص الحالة في الحساب واطلب إعادة الإرسال صراحةً. إعادة الإرسال تعيد الإشعار فقط، دون توليد جديد أو رسوم.

تحديث نقطة النهاية أو تدوير المفتاح يزيد الإصدار ويوقف سجلات التسليم القديمة المعلقة. لا يُستخدم العنوان والمفتاح الحاليان إلا عند إعادة إرسال صريحة. التعطيل يمنع المحاولات الجديدة، لكنه لا يسحب الطلبات التي أُرسلت بالفعل؛ حدّث المستقبِل بعد التدوير. راجع علاقة الحالة بالتسوية في المهام غير المتزامنة وضمان عدم تكرار التنفيذ.

نقاط النهاية ذات الصلة

• إنشاء مهمة توليد فيديو
• الحصول على نتيجة الفيديو