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

تشرح هذه الصفحة كيف تسلّم TakeTheme الويب هوك — الطلب الذي ترسله، وكيف تُعاد المحاولة عند الفشل، ومتى تُعطَّل العناوين تلقائيًا — وكيف تدير عناوينك عبر الـ API.

طلب التسليم

يُسلَّم كل حدث بطلب POST بحمولة JSON (الغلاف) وبالترويسات التالية:

الترويسة	مثال	الوصف
Content-Type	application/json	الحمولة دائمًا JSON.
X-TakeTheme-Signature	t=1751371200,v1=5257a8…	توقيع HMAC — راجع التحقق من التواقيع.
X-TakeTheme-Event	order.paid	نوع الحدث. يطابق type في الغلاف.
X-TakeTheme-Delivery	3f1c2b9e-8a4d-…	معرّف التسليم/الحدث الفريد. يطابق id في الغلاف. أسقِط المكرر اعتمادًا عليه.
User-Agent	TakeTheme-Webhooks/1.0	يعرّف وكيل التسليم لدى TakeTheme.

ما الذي يُعدّ نجاحًا

• نجاح: يردّ عنوانك بأي رمز 2xx خلال 10 ثوانٍ.
• فشل: أي رمز غير 2xx، أو انتهاء المهلة، أو خطأ اتصال، أو إعادة توجيه (استجابات 3xx لا تُتبَّع).

ردّ بمجرد استلامك الحدث بأمان — أكّد بالرمز 200 ثم عالج الحدث لاحقًا. فتنفيذ عمل بطيء قبل الرد يعرّضك لانتهاء المهلة وإعادة محاولات لا داعي لها.

إعادة المحاولة

عند فشل التسليم، تعيد TakeTheme المحاولة بـفواصل متزايدة أُسّيًا مع تشويش عشوائي، حتى 8 محاولات إجمالًا. وقبل المحاولة رقم n (حيث n ≥ 2؛ فالمحاولة الأولى هي التسليم الأصلي) تنتظر TakeTheme 30s × 4^(n-1) بحد أقصى 6 ساعات، مع تشويش عشوائي ±15%:

المحاولة	التأخير التقريبي بعد السابقة	الزمن التقريبي منذ المحاولة الأولى
1	—	0
2	نحو دقيقتين	نحو دقيقتين
3	نحو 8 دقائق	نحو 10 دقائق
4	نحو 32 دقيقة	نحو 42 دقيقة
5	نحو 2.1 ساعة	نحو 2.8 ساعة
6	نحو 6 ساعات (الحد الأقصى)	نحو 8.8 ساعة
7	نحو 6 ساعات	نحو 14.8 ساعة
8	نحو 6 ساعات	نحو 20.8 ساعة

وبعد فشل المحاولة الثامنة، يُعلَّم التسليم مستنفدًا ولا تُعاد محاولته تلقائيًا بعدها. ويمكنك إعادة إرسال التسليمات المستنفدة بعد أن يصبح عنوانك سليمًا.

أمان التكرار

لأن الرد البطيء الذي ينجح في النهاية قد يُطلق إعادة محاولة، فقد يُسلَّم الحدث نفسه أكثر من مرة. أسقِط المكرر اعتمادًا على ترويسة X-TakeTheme-Delivery (المساوية لـ id في الغلاف) حتى تصبح إعادة المعالجة بلا أثر.

التعطيل التلقائي

حمايةً من العناوين المعطّلة باستمرار ومنعًا لحركة لا تنتهي، تعطّل TakeTheme تلقائيًا أي عنوان بعد 3 تسليمات مستنفدة خلال نافذة 7 أيام. وعندها:

• تُضبط قيمة isActive للعنوان على false ويتوقف عن استقبال الأحداث.
• يُرسَل بريد إشعار بالفشل إلى مالك المتجر.

أعد تفعيل العنوان (من لوحة التحكم أو عبر PATCH بضبط isActive: true) بعد معالجة المشكلة الأساسية، ثم أعد إرسال التسليمات التي فاتتك إن أردت.

سجلات التسليم

تُسجَّل كل محاولة تسليم. اجلب السجلات الأخيرة لعنوان ما لتتبّع أسباب الفشل:

curl -X GET "https://api.taketheme.com/api/v1/store/webhooks/endpoints/{id}/logs?page=1&limit=20" \
  -H "tt-api-key: tt_xxx"

يتضمن كل مدخل في السجل:

الحقل	الوصف
eventType	الحدث الذي سُلِّم.
eventId	معرّف التسليم/الحدث.
status	pending أو success أو failed أو exhausted.
attempt	رقم المحاولة التي يعكسها هذا السجل.
httpStatus	رمز HTTP الذي أعاده عنوانك (0 عند خطأ شبكة أو انتهاء مهلة).
responseBody	أول كيلوبايت من حمولة رد عنوانك.
errorMessage	تفصيل الخطأ عند فشل التسليم (انتهاء مهلة، DNS، TLS، مضيف محظور…).
nextRetryAt	موعد المحاولة التالية (للسجلات failed التي ما زالت تُعاد).
deliveredAt	وقت نجاح التسليم (للسجلات success).

إدارة العناوين

يمكن إدارة العناوين من لوحة التحكم (الإعدادات ← الويب هوك) أو عبر واجهة REST أدناه. وكل العناوين تحت:

https://api.taketheme.com/api/v1/store/webhooks

تُصادَق الطلبات بمفتاح tt-api-key (أو بجلسة لوحة التحكم) وتتطلب صلاحية الوصول إلى إعدادات المتجر. ويجب أن تشمل باقتك الوصول إلى الويب هوك (canAccessWebhooks)، وإلا أعادت هذه الطلبات الرمز 403.

حد العناوين

لا يمكن للمتجر أن يتجاوز 5 عناوين ويب هوك. احذف العناوين غير المستخدمة قبل إنشاء عناوين جديدة.

عرض العناوين

curl -X GET "https://api.taketheme.com/api/v1/store/webhooks/endpoints?page=1&limit=20" \
  -H "tt-api-key: tt_xxx"

يعيد عناوينك مع حذف مفتاح التوقيع.

إنشاء عنوان

curl -X POST "https://api.taketheme.com/api/v1/store/webhooks/endpoints" \
  -H "tt-api-key: tt_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/taketheme",
    "events": ["order.placed", "order.paid"],
    "description": "Production order sync",
    "metadata": { "team": "fulfillment" }
  }'

حقل الحمولة	مطلوب	ملاحظات
url	نعم	يجب أن يبدأ بـ https://. وتُرفض المضيفات الداخلية والخاصة.
events	نعم	مصفوفة غير فارغة من أنواع الأحداث.
description	لا	حتى 256 حرفًا.
metadata	لا	أزواج مفتاح/قيمة نصية حرة لاستخدامك الخاص.

يعيد الرمز 201 مع العنوان ومفتاح secret لمرة واحدة (whsec_…). احفظه الآن — فهو لا يُعرض مرة أخرى أبدًا.

جلب عنوان

curl -X GET "https://api.taketheme.com/api/v1/store/webhooks/endpoints/{id}" \
  -H "tt-api-key: tt_xxx"

تحديث عنوان

غيّر الرابط أو الأحداث المشترَك بها أو الوصف، أو فعّله وعطّله:

curl -X PATCH "https://api.taketheme.com/api/v1/store/webhooks/endpoints/{id}" \
  -H "tt-api-key: tt_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["order.placed", "order.paid", "order.fulfilled"],
    "isActive": true
  }'

حذف عنوان

curl -X DELETE "https://api.taketheme.com/api/v1/store/webhooks/endpoints/{id}" \
  -H "tt-api-key: tt_xxx"

يعيد الرمز 204 No Content.

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

curl -X POST "https://api.taketheme.com/api/v1/store/webhooks/endpoints/{id}/rotate-secret" \
  -H "tt-api-key: tt_xxx"

يعيد مفتاح secret جديدًا (يُعرض مرة واحدة) ويُبطل القديم فورًا. راجع تدوير مفتاح التوقيع.

إعادة إرسال التسليمات المستنفدة

أعد إدراج كل تسليم بلغ حالة exhausted لعنوان ما — وهو مفيد بعد معالجة انقطاع:

curl -X POST "https://api.taketheme.com/api/v1/store/webhooks/endpoints/{id}/replay-exhausted" \
  -H "tt-api-key: tt_xxx"

{ "replayed": 12 }

تدخل التسليمات المُعاد إرسالها مسار التسليم المعتاد (بمحاولات جديدة). تأكد أولًا من أن العنوان مفعّل وسليم.

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

• تحقّق من كل طلب. ارفض كل ما يفشل في التحقق من التوقيع. راجع التحقق من التواقيع.
• أكّد بسرعة وعالج لاحقًا. أعد 2xx خلال ثانيتين، وحوّل العمل البطيء إلى طابور مهام.
• كن آمن التكرار. أسقِط المكرر اعتمادًا على X-TakeTheme-Delivery، فإعادة المحاولة وإعادة الإرسال قد تُسلّم الحدث نفسه أكثر من مرة.
• لا تفترض ترتيبًا. اعتمد على حقول الحالة في الحمولة بدل تسلسل الوصول.
• راقب سجلاتك. راجع سجلات التسليم (أو سجلات خادمك) بحثًا عن إخفاقات متكررة قبل بلوغ عتبة التعطيل التلقائي.
• اشترك بحدود ضيقة. اشترك فقط في الأحداث التي تعالجها فعلًا لتقليل الحمل على عنوانك.