Webhooks 101: كيف تخبرك LotShow API بأن الصورة جاهزة

تحتاج صورة الاستوديو إلى بعض الوقت لتكتمل. يمكن لنظامك أن يسأل LotShow كل بضع ثوانٍ هل انتهت، أو يمكن لـ LotShow أن يخبر نظامك لحظة انتهائها. الطريقة الثانية هي webhook، وبها تسلّم LotShow API النتائج.

الاستطلاع أم webhooks

الاستطلاع يعني أن تستدعي شيفرتك GET /v1/jobs/{id} على فترات منتظمة حتى تتغير الحالة. هذا يعمل، لكن معظم هذه الطلبات تعود دون جديد، وكلما عالجت سيارات أكثر، زاد عدد الطلبات.

أما webhook فيقلب الأمر. حين تنشئ مهمة، تعطي LotShow رابطًا. وحين تنتهي المهمة، يرسل LotShow طلب HTTPS POST إلى هذا الرابط مع النتيجة. ولا يفعل نظامك شيئًا حتى يكون هناك ما يستدعي ذلك.

الأحداث

• job.completed: صورة الاستوديو جاهزة، مع رابط الصورة النهائية.
• job.failed: تعذّر إنهاء صورة، واستُردّت نقطتها.
• credits.low: انخفض رصيدك المشترك إلى أقل من 20 نقطة.

تختار الأحداث التي تستقبلها كل نقطة نهاية، فيستطيع نظام المخزون الاستماع إلى الصور الجاهزة، بينما لا تسمع أداة الفوترة إلا عن انخفاض الرصيد.

كيف يبدو الإرسال

تصل المهمة المنتهية على شكل جسم JSON صغير:

{
  "event": "job.completed",
  "created_at": "2026-10-14T09:41:40.000Z",
  "id": "Hn4kR2pXq8VbT1sLw0Za",
  "backdrop": "white-hall",
  "vehicle_id": "pQ7mT2vK9cLx4RbN1sHd",
  "name": "stock-4471",
  "output_url": "https://firebasestorage.googleapis.com/v0/b/…/default.jpg?alt=media&token=…",
  "seconds": 62,
  "credits_left": 319
}

الحقل id هو معرّف المهمة الذي حصلت عليه عند إنشائها. لهذا من المفيد أن تحفظ معرّف المهمة بجانب رقم المخزون في نظامك: يخبرك webhook أي مهمة انتهت، وتخبرك سجلاتك لأي سيارة تعود.

بناء نقطة نهاية جيدة

1. استجب بسرعة. ردّ برمز حالة 2xx فور وصول الحدث، ثم أنجز العمل الفعلي، مثل تنزيل الصورة، في الخلفية.
2. توقّع التكرار. قد يصل الإرسال نفسه أكثر من مرة، بعد انتهاء مهلة مثلًا، لأن LotShow يعيد المحاولة حتى تستجيب نقطة النهاية لديك. تحقق هل عالجت الحدث من قبل قبل أن تتصرف بناءً عليه مجددًا.
3. لا تفترض الترتيب. مهمتان أُرسلتا بفارق ثانية قد تنتهيان بأي ترتيب. طابق النتائج بمعرّف المهمة، لا بوقت وصولها.
4. تحقق من التوقيع. كل إرسال موقّع بسر التوقيع الخاص بحسابك، الموجود في الإعدادات، ضمن الترويسات webhook-id وwebhook-timestamp وwebhook-signature (وفق مخطط Standard Webhooks). ارفض أي شيء لا يجتاز التحقق.
5. سجّل كل شيء. احتفظ بالجسم الخام ووقت كل إرسال. حين يبدو أن شيئًا ما خطأ، فالسجل أول مكان ستبحث فيه.

الاختبار قبل الإطلاق

لكل نقطة نهاية في الإعدادات زر «إرسال اختبار»، وفي واجهة API يوجد POST /v1/webhooks/{id}/test. كلاهما يرسل حدثًا تجريبيًا إلى نقطة النهاية لديك، لتختبر معالجك دون إنفاق نقاط. وأداة فحص الطلبات أو النفق المحلي وسيلة جيدة لترى بالضبط ما تستقبله نقطة النهاية.

مستعد للبناء؟ مفاتيح API متاحة في باقتَي «احترافي» و«النخبة»: أنشئ مفتاحًا من الإعدادات، ضمن مفاتيح API.