Webhooks

نقاط نهاية Webhook

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

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

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

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

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

{
  "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"
}

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

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

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• call.graded
• issue.reported
• test-call.completed
• alert.triggered

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

• 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"

يعيد مصفوفة من كائنات نقاط النهاية.

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

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 مع كائن نقطة النهاية المحدّث.

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

أرسل حدث webhook.test اصطناعيًا إلى نقطة نهاية واحدة باستخدام مسار التسليم المعتاد، بما في ذلك تسلسل JSON المعياري، وX-ThunderPhone-Signature، وتسجيل التسليم، وتتبّع إعادة المحاولة. يستهدف الاختبار نقطة النهاية المحددة بغض النظر عن عامل تصفية 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"
}

تعيد واجهة API القيمة 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 لنقطة نهاية. إذا فشلت المحاولة الأولى، يتبع التسليم جدول إعادة المحاولة نفسه المستخدم في عمليات تسليم الأحداث العادية.

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

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

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

ذو صلة#