نقاط نهاية Webhook

أدِر عدة عناوين URL لـ Webhook باستخدام أسرار خاصة بكل نقطة نهاية وفلاتر للأحداث.

يتيح لك نظام الويب هوك القائم على نقاط النهاية تسجيل وجهات متعددة لكل مؤسسة، لكل منها سرّها الخاص وحالتها الخاصة واشتراكها الخاص في مجموعة فرعية من أنواع الأحداث. هذا هو النموذج الموصى به لجميع عمليات التكامل الجديدة.

قارنه بـالويب هوك القديم أحادي الرابط، المُحتفَظ به للتوافق مع الإصدارات السابقة، ولكنه يدعم رابط URL واحدًا فقط لكل مؤسسة.

نقاط النهاية#

كائن نقطة النهاية#

{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "agent_id": 42,
  "agent_name": "Support Agent",
  "secret_hint": "a1b2…9f0e",
  "paused_at": null,
  "pause_last_error": "",
  "pause_undelivered_count": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

أنواع الأحداث الصالحة#

يُتحقق من events مقابل هذه المجموعة الدقيقة — تُرجع القيم خارج القائمة 400. راجع كتالوج الأحداث للاطلاع على بنية الحمولة لكل نوع.

• telephony.incoming، telephony.complete، telephony.tool، telephony.turn
• web.incoming، web.complete، web.tool، web.turn
• sms.sent، sms.failed
• sms.received (محجوز؛ لم يُصدر بعد)
• call.graded، call.data_extracted، call.transfer_completed
• campaign.completed
• issue.reported، issue.escalated
• test-call.completed
• alert.triggered

لا يحتوي issue.escalated على سياق وكيل ويُسلَّم فقط إلى نقاط النهاية على مستوى المؤسسة.

لا يمكن اختيار voice.ready وvoice.failed صراحةً. لتلقيهما، أنشئ نقطة نهاية على مستوى المؤسسة مع events: []. تتلقى قائمة الأحداث الفارغة كل حدث مدعوم باستثناء telephony.turn وweb.turn، اللذين يجب اختيارهما صراحةً.

حالات نقطة النهاية#

• active — تتدفق عمليات التسليم بشكل طبيعي.
• disabled — مُعلّق يدويًا عبر PATCH. لا تُرسل أي طلبات. نحن لا نغيّر حالة نقطة نهاية disabled مطلقًا؛ إعادة تحويلها إلى active قرارك دائمًا.
• failing — يُضبط تلقائيًا عندما تستهلك عملية تسليم إلى نقطة النهاية جدول إعادة المحاولة بالكامل (8 محاولات خلال 24 ساعة) من دون الحصول على استجابة 2xx. لا تتلقى نقطة النهاية الفاشلة أي حركة مرور إضافية. نرسل بريدًا إلكترونيًا إلى المالكين والمشرفين في مؤسستك عند حدوث ذلك، وتعرض لوحة التحكم نقطة النهاية المعلّقة مع زر إعادة التفعيل. بعد إصلاح نقطة النهاية، أعد حالة PATCH إلى active؛ تستأنف عمليات التسليم التي لم ينتهِ جدول إعادة محاولاتها بعد من حيث توقفت.

سرد نقاط النهاية#

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

يُرجع مصفوفة من كائنات نقاط النهاية. مرّر ?agent_id=42 لإرجاع نقاط النهاية المقيَّدة بذلك الوكيل فقط.

نقاط النهاية المقيَّدة بالوكيل#

تتلقى نقاط النهاية على مستوى المؤسسة كل حدث مطابق. تتلقى نقطة النهاية ذات agent_id الأحداث المطابقة فقط للمكالمات التي يعالجها ذلك الوكيل؛ أما الأحداث التي لا تحتوي على سياق وكيل، مثل alert.triggered، فلا تصل إليها أبدًا. يمكنك أيضًا إنشاء هذه النقاط وإدارتها من قسم خطافات الويب في منشئ الوكيل.

إنشاء نقطة نهاية#

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call events",
    "url":    "https://example.com/thunderphone/hook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'

result = requests.post(
    "https://api.thunderphone.com/v1/developer/webhook-endpoints",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "label":  "Production — Call events",
        "url":    "https://example.com/thunderphone/hook",
        "events": ["telephony.incoming", "telephony.complete"],
    },
).json()
secret = result["secret"]
endpoint_id = result["id"]

حقول الطلب#

يعيد 201 Created مع كائن نقطة النهاية المحدّث، بالإضافة إلى حقل secret إضافي في المستوى الأعلى يحتوي على مفتاح التوقيع الخام، وهو سلسلة سداسية عشرية من 48 حرفًا:

{
  "id": "c4d5e6f7-…",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e"
}

تحديث نقطة نهاية#

curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call + Grade events",
    "events": ["telephony.incoming", "telephony.complete", "call.graded"]
  }'

يعيد 200 OK مع كائن نقطة النهاية المحدّث.

تدوير سر التوقيع#

استبدل سر توقيع نقطة النهاية، مثلاً عند فقدانه أو احتمال تسرّبه. بالنسبة إلى نقطة نهاية مقيّدة بوكيل، يمكنك أيضاً استخدام لوحة التحكم: افتح قسم خطافات الويب الخاص بالوكيل واختر إعادة إنشاء السر في نقطة النهاية. تُدوَّر نقاط النهاية على مستوى المؤسسة عبر واجهة API.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

يعيد 200 OK:

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}

إرسال تسليم اختباري#

أرسل حدث webhook.test اصطناعيًا إلى نقطة نهاية واحدة باستخدام مسار التسليم المعتاد، بما في ذلك تسلسل JSON القياسي، وترويستا التوقيع، وتسجيل التسليم، ومتابعة إعادة المحاولة. يستهدف الاختبار نقطة النهاية المحددة بغض النظر عن فلتر events الخاص بها.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

تتلقى نقطة النهاية غلافًا مثل:

{
  "data": {
    "message": "ThunderPhone webhook test",
    "sent_at": "2026-07-17T20:12:34.567890+00:00"
  },
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "type": "webhook.test"
}

تُرجع واجهة برمجة التطبيقات 200 OK بعد المحاولة الأولى، حتى إذا أعادت الوجهة خطأً. افحص success وstatus وresponse_code وerror لمعرفة نتيجة التسليم:

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

يُعد webhook.test حدثًا اصطناعيًا ولا يمكن إضافته إلى اشتراك events لنقطة نهاية. إذا أخفقت المحاولة الأولى، يعيد ThunderPhone محاولتها مرة واحدة بعد نحو دقيقة ثم يتوقف؛ ويظهر التسليم عندئذٍ بالحالة status: "failed" ضمن تصحيح أخطاء عمليات التسليم. لا يؤدي التسليم الاختباري أبدًا إلى وضع علامة failing على نقطة النهاية.

لتهيئة مشغّل يستند إلى بنية حدث حقيقية، مرّر event_type اختياريًا. يظل التسليم اصطناعيًا ويحتوي على "sample": true؛ وتستخدم العينات المتعلقة بالمكالمات call_id: 0 وagent_id: 0.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'

يقبل event_type أي قيمة من أنواع الأحداث الصالحة. يؤدي حذفه إلى الحفاظ على سلوك webhook.test العام.

حذف نقطة نهاية#

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

يُرجع 204 No Content. يتوقف التسليم إلى عنوان URL فورًا؛ وتُلغى عمليات إعادة المحاولة قيد التنفيذ.

تصحيح أخطاء عمليات التسليم#

قبل استنتاج أن ويبهوك لم يُرسل، افحص GET /v1/developer/webhook-deliveries. يعرض المحاولات الأخيرة من نظامَي ويبهوك كليهما، بما في ذلك معرّف المكالمة، وأصل عنوان URL، وحالة HTTP، وعدد المحاولات، وفئة الإخفاق المسموح بها، ووقت إعادة المحاولة التالي. لا يُرجع أبدًا حمولة الحدث أو النص المفرغ أو نص الخطأ المخزن أو نص الاستجابة أو مسار عنوان URL.

يمكنك أيضًا الاطلاع على السجل الأخير نفسه في الوكلاء → اختر وكيلًا → ويبهوك → عمليات التسليم الأخيرة. تعرض الصفوف تسمية نقطة النهاية وأصل عنوان URL المستخدم في أحدث محاولة. هذه حالة تشغيلية وليست سجل تدقيق غير قابل للتغيير: إذ يؤدي حذف نقطة النهاية أيضًا إلى حذف صفوف تسليمها.

بالنسبة إلى 404 من n8n، تأكد أولًا من أن سير العمل نشط، ويقبل POST، ويستخدم عنوان URL لويبهوك الإنتاج بدلًا من عنوان URL للاختبار. يشير 401 أو 403 إلى المصادقة أو التحقق من التوقيع؛ وتشير المهلات إلى زمن استجابة الوجهة أو توفرها؛ وتشير أخطاء TLS إلى سلسلة الشهادات أو اسم المضيف أو انتهاء الصلاحية.

ذو صلة#