بدل أن يستعلم تطبيقك باستمرار لمعرفة هل اكتمل رد خلفية أو انتهت دفعة، يمكنه استقبال إشعار عند وقوع الحدث عبر Webhooks في OpenAI API. لكن استقبال طلب HTTP لا يكفي لاعتباره موثوقًا أو لتنفيذ أثره مرتين. هذا دليل للتحضير لعام 2027 وفق الإمكانات التي روجعت في 27 أكتوبر 2026، وليس إعلانًا عن واجهة مستقبلية.
إعداد عنوان استقبال للأحداث
من إعدادات Webhooks في لوحة المشروع، أنشئ نقطة استقبال باسم مرجعي، وعنوان عام لخادم تتحكم فيه، وحدد أنواع الأحداث التي تحتاجها. عند وقوع حدث مشترك فيه، يرسل النظام طلب HTTP POST إلى العنوان المحدد. ويمكن إرسال أحداث اختبار ببيانات نموذجية من صفحة الإعدادات قبل ربط المعالجة ببيانات العمل الفعلية.
بعد الإنشاء يظهر سر توقيع تستخدمه للتحقق من الطلبات في الخادم. احفظه بأمان عند ظهوره، لأنك لن تتمكن من عرضه مرة أخرى. لا تضعه في تطبيق المتصفح أو المستودع العام، ولا تخلط بينه وبين مفتاح API المستخدم لاسترجاع الردود. إذا ضاع سر التوقيع أو انكشف، استخدم تدويره لإنشاء بديل.
تحقق من التوقيع قبل معالجة المحتوى
تحتاج عملية التحقق إلى جسم الطلب الأصلي وترويساته وسر التوقيع. في JavaScript يمكن استخدام client.webhooks.unwrap(req.body, req.headers, webhook_secret)، وفي Python يمكن استخدام client.webhooks.unwrap(request.data, request.headers, secret=webhook_secret). تتحقق الدالة من التوقيع وتعيد الحدث، وتثير خطأ إذا كان التوقيع غير صالح.
لا تحلل JSON ثم تعيد بناءه قبل التحقق. مثال Express يستخدم express.text({ type: "application/json" }) بدل express.json() حتى يبقى الجسم النصي الخام متاحًا للتحقق. وجود حقل type باسم مألوف لا يثبت أن المرسل هو الخدمة؛ ارفض الطلب ذي التوقيع غير الصحيح بدل تشغيل منطق العمل عليه.
الإشعار ليس النص الكامل للرد
من أمثلة الأحداث response.completed، الذي يشير إلى اكتمال رد في الخلفية. يتضمن الحدث معرفًا في data.id يخص الرد، ويمكن استخدامه مع client.responses.retrieve(response_id) لاسترجاع النتيجة. لا تتعامل مع معرف الحدث نفسه على أنه معرف الرد، ولا تفترض أن جسم الإشعار يحتوي نص الإجابة كاملًا.
حدد في الخادم ما ينبغي فعله لكل نوع مشترك فيه. فإشعارات اكتمال الدفعات أو وظائف الضبط الدقيق ليست استجابة محادثة جديدة، ولكل منها بياناته ومساره. ابدأ بنوع واحد تستطيع اختباره ثم وسع الاشتراكات حسب حاجة التطبيق.
رد سريع ومعالجة دون تكرار
أعد رمز نجاح من فئة 2xx بسرعة لتأكيد الاستلام، وانقل المعالجة غير البسيطة إلى عامل خلفية بدل إبقاء الطلب مفتوحًا. إذا لم يصل نجاح أو لم يستجب الخادم خلال ثوانٍ قليلة، تعاد محاولة التسليم بتراجع أُسّي لمدة تصل إلى 72 ساعة.
قد يصل الحدث نفسه أكثر من مرة؛ استخدم ترويسة webhook-id مفتاحًا لمنع التكرار. احفظ حالة المعالجة في تطبيقك بحيث لا يؤدي تكرار الإشعار إلى تكرار رسالة أو مهمة أو إجراء مالي. ولا تعتبر الاستلام الناجح وحده دليلًا على أن العمل الخلفي انتهى بنجاح.
لا تتبع الخدمة إعادة التوجيه من فئة 3xx، بل تعاملها كفشل؛ لذلك ضع عنوان الاستقبال النهائي مباشرة. وللاختبار المحلي تحتاج عنوانًا يمكن الوصول إليه من الإنترنت، لا عنوان localhost وحده. راجع إعداد Webhooks والتحقق من التوقيع قبل تشغيل نقطة الاستقبال.
