Webhooks محليا

نقطة نهاية webhook عندك تعمل على localhost، و lahsab لا يستطيع الوصول إليها. بدل نفق من طرف ثالث، تعكس أداة CLI اتجاه الاتصال: تتصل هي بخوادم lahsab، وتستقبل أحداث حسابك التجاري لحظة وقوعها، ثم تعيد إرسالها بطلبات POST إلى خادمك المحلي، موقعة تماما كما في الإنتاج. هكذا يمر كودك الخاص بالتحقق من التوقيع بنفس المسار، وبنفس سر التوقيع whsec_ الخاص ببيئتك.

الاستماع

تصدير مفتاح Sandbox (تجده في قسم المطورين):
```
export LAHSAB_API_KEY=lsk_sandbox_…
```
تشغيل المستمع نحو نقطة النهاية المحلية:
```
lahsab listen --forward-to http://localhost:3000/webhooks/lahsab
```
إطلاق حدث، من تطبيقك، أو من لوحة التحكم، أو عبر lahsab trigger:
```
lahsab trigger invoice.paid
```

تعرض أداة CLI كل حدث مستقبل، مع رمز استجابة نقطة النهاية وزمن الاستجابة:

lahsab listen
  API      http://localhost:3100
  Forward  http://localhost:3000/webhooks/lahsab

17:42:03 Connecté : Ma Boutique (sandbox)
17:42:03 Signature avec le secret whsec_4f2…
17:42:03 En attente d'events… (Ctrl+C pour quitter)
17:42:19 invoice.paid [a1b2c3…] → 200 (34 ms)

عند الانطلاق يعرض المستمع سر التوقيع المستعمل: وهو whsec_ الخاص ببيئة Sandbox عندك (ينشأ تلقائيا إن لم يكن موجودا). ضعه في ملف .env لخادمك المحلي، فيعمل التحقق من التوقيع دون أي تعديل بين التطوير والإنتاج.

لتصفية أنواع الأحداث المستقبلة:

lahsab listen \
  --forward-to http://localhost:3000/webhooks/lahsab \
  --events invoice.paid,payment.confirmed

إطلاق الأحداث

يبني الأمر lahsab trigger سيناريو كاملا في بيئة Sandbox، بما في ذلك بيانات التجربة، ويطلق الحدث المرتبط به، دون مغادرة الطرفية:

السيناريو	ما يحدث
`payment.intent_created`	ينشئ intent
`payment.proof_submitted`	intent مع وصل اصطناعي
`payment.proof_validated`	intent مع وصل اعتبر متوافقا، والدفعة غير مؤكدة
`payment.confirmed`	intent مع وصل وتأكيد
`payment.rejected`	intent مع وصل ورفض
`payment.expired`	intent مع انتهاء الصلاحية
`invoice.paid`	منتج وتسعيرة وزبون واشتراك وفاتورة مدفوعة
`billing.tick`	يفرض تشغيل ساعة الفوترة

خلف الكواليس

يستهلك المستمع تدفق SSE مصادقا عليه بمفتاح API، ويمكن معاينته مباشرة عبر curl:

curl -N http://localhost:3100/webhooks/listen \
  -H "x-api-key: lsk_sandbox_CLE" \
  -H "accept: text/event-stream"

ثلاثة أنواع من الرسائل: ready (التاجر والبيئة وسر التوقيع)، و event (يحمل id و type و createdAt و body، وهو نص JSON الكامل الذي يعاد توقيعه وإرساله)، و ping (لإبقاء الاتصال حيا). عند إعادة الاتصال ترسل أداة CLI آخر id مستقبل (عبر Last-Event-ID) فيعيد الخادم إرسال الأحداث الفائتة.

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