خطافات الويب (Webhooks)

تسمح لك خطافات الويب (Webhooks) بتلقي إشعارات غير متزامنة عند اكتمال عملية توليدية. بدلاً من الاستعلام يدويًا عن نقطة النهاية /api/v1/status/{id} للتحقق من التحديثات، يقوم نظامنا بدفع الحمولة النهائية مباشرة إلى خادمك بمجرد انتهاء المهمة.

كيفية استخدام خطافات الويب

لاستخدام خطافات الويب مع واجهة برمجة التطبيقات (API) الخاصة بنا، ما عليك سوى إلحاق المعامل webhook_url بطلب /run الخاص بك:

عندما تنتهي العملية التوليدية (إما بنجاح أو إذا واجهت خطأ في وقت التشغيل)، سيرسل المرسل الخاص بنا طلب POST إلى عنوان URL لخطاف الويب المحدد الخاص بك والذي يحتوي على حمولة الحالة الكاملة.

مثال: استخدام خطافات الويب مع نقطة النهاية /run

fetch("https://fititon.app/api/v1/run?webhook_url=https://your-server.com/webhook", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    model_name: "product-to-model",
    inputs: {
      image: "http://example.com/path/to/garment.jpg",
      // ... other inputs
    }
  }),
});

حمولات خطاف الويب (Webhook Payloads)

الحمولة التي يتم تسليمها إلى عنوان URL لخطاف الويب الخاص بك مطابقة للحمولة التي يتم إرجاعها بواسطة نقطة النهاية /v1/status/{id}. وهي تحتوي على الحالة النهائية للمهمة.

حمولة النجاح

عند اكتمال العملية بنجاح، سيتلقى عنوان URL لخطاف الويب الخاص بك طلب POST مع تعيين status على "success" والنتائج في مصفوفة output:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1",
  "status": "success",
  "output": [
    "https://cdn.fititon.app/users/123/results/output_0.png"
  ],
  "error": null,
  "created_at": "2026-07-24T17:30:00.000Z",
  "updated_at": "2026-07-24T17:31:15.000Z"
}

حمولة الخطأ

إذا فشلت العملية بسبب خطأ في وقت التشغيل (مثل ملابس غير قابلة للتعرف، أو فلاتر إشراف صارمة)، سيتلقى عنوان URL لخطاف الويب الخاص بك سلسلة الخطأ الدقيقة.

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1",
  "status": "failed",
  "output": null,
  "error": {
    "name": "InputValidationError",
    "message": "The provided garment image could not be processed due to poor lighting."
  },
  "created_at": "2026-07-24T17:30:00.000Z",
  "updated_at": "2026-07-24T17:30:12.000Z"
}

أمان خطاف الويب (Webhook Security)

للتأكد من أن خطافات الويب التي تتلقاها تنشأ بالفعل من Fit It On ولم يتم تزويرها بواسطة طرف ثالث ضار، يجب عليك تنفيذ آلية تحقق.

أبسط طريقة لتأمين خطافات الويب الخاصة بك هي إلحاق رمز سري بـ webhook_url الذي توفره في طلب /v1/run الخاص بك.

مثال: استخدام رمز سري

عند بدء عملية توليدية، ألحق سلسلة عشوائية للغاية بمعاملات استعلام URL الخاصة بك:

// تأكد من ترميز URL لخطاف الويب إذا كان يحتوي على معاملات استعلام!
const myWebhookUrl = encodeURIComponent("https://your-server.com/webhook?token=a8f9c2d1e5b47...");

fetch(`https://fititon.app/api/v1/run?webhook_url=${myWebhookUrl}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  // ...
  body: JSON.stringify({
    model_name: "product-to-model",
    inputs: {
      image: "http://example.com/path/to/garment.jpg",
    }
  }),
});

عندما يتلقى خادمك طلب POST لخطاف الويب، ما عليك سوى التحقق من أن معامل استعلام token يطابق سلسلتك السرية قبل معالجة حمولة JSON.

التسليم المضمون وإعادة المحاولة

يطبق نظامنا آلية إعادة محاولة على مستوى المؤسسات لضمان عدم تفويت أي تسليم لخطاف الويب، حتى لو واجه خادمك تعطلًا مؤقتًا.

• المهلة: يفرض المرسل الخاص بنا مهلة صارمة مدتها 15 ثانية. يجب أن يقر خادمك بخطاف الويب برمز حالة HTTP 2xx في غضون 15 ثانية. إذا كنت بحاجة إلى إجراء معالجة مكثفة (مثل تنزيل الصورة)، فيجب عليك الاستجابة لخطاف الويب أولاً، ومعالجة البيانات بشكل غير متزامن.
• الإخفاقات: إذا أرجع خادمك رمز حالة غير 2xx (مثل 500 Internal Server Error)، أو فشل في الاستجابة في غضون 15 ثانية، فإننا نعتبر التسليم فاشلاً.
• التراجع الأسي: سيحاول النظام ما يصل إلى 5 محاولات إعادة باستخدام التراجع الأسي (على سبيل المثال، إعادة المحاولة في 5 دقائق، 15 دقيقة، 45 دقيقة، إلخ).

إذا كنت بحاجة إلى معرفة محاولة إعادة المحاولة التي تصل إلى خادمك حاليًا، يمكنك فحص رأس x-fititon-retry-count المتضمن في كل طلب خطاف ويب.

أفضل الممارسات

1. تنفيذ خاصية الثبات (Idempotency): بسبب ظروف الشبكة وآلية إعادة المحاولة لدينا، من الممكن تقنيًا أن يتلقى خادمك نفس خطاف الويب أكثر من مرة. يجب عليك استخدام حقل id للتحقق مما إذا كنت قد عالجت الحدث بالفعل.
2. الاستجابة بسرعة: أرجع دائمًا حالة 200 OK فورًا قبل تنزيل الصور أو تحديث قواعد البيانات.
3. التحقق دائمًا من خطافات الويب: فكر في تنفيذ آلية تحقق (مثل الرمز السري لعنوان URL المذكور أعلاه) للتأكد من أن خطافات الويب تأتي من خدمتنا ومنع الجهات الخبيثة من تزوير الحمولات.