نقاط نهاية Webhook

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

نقاط النهاية

الطريقة	المسار	الدور المطلوب	الوصف
`GET`	`/v1/developer/webhook-endpoints`	`admin+`	سرد نقاط النهاية
`POST`	`/v1/developer/webhook-endpoints`	`admin+`	إنشاء نقطة نهاية
`PATCH`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	تحديث التسمية / عنوان URL / الأحداث / الحالة
`DELETE`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	حذف نقطة نهاية
`POST`	`/v1/developer/webhook-endpoints/{endpoint_id}/test`	`admin+`	إرسال تسليم اختبار موقّع

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

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

الحقل	النوع	الوصف
`id`	UUID	معرّف نقطة النهاية
`label`	string	اسم العرض، من 1 إلى 120 حرفًا
`url`	string	عنوان HTTPS؛ يُسمح بـ`http://localhost` للتطوير
`events`	array of string	أنواع الأحداث المشترَك بها (راجع القيم الصالحة). تشترك المصفوفة الفارغة في جميع الأحداث
`status`	string	`active` أو `disabled` (متوقف يدويًا) أو `failing` (يُعيّن تلقائيًا عندما يستنفد تسليمٌ جدول إعادة المحاولة البالغ 24 ساعة دون الحصول على أي استجابة 2xx)
`secret_hint`	string	أول 4 وآخر 4 أحرف من سر التوقيع مع علامة حذف (`a1b2…9f0e`) — تكفي لمطابقة السر الذي حفظته محليًا دون كشف القيمة الكاملة
`created_at`, `updated_at`	timestamp

يُعاد secret الكامل لنقطة النهاية مرة واحدة عند الإنشاء ولا يُعاد مجددًا. خزّنه بأمان — إذا فقدته، احذف نقطة النهاية وأنشئها مجددًا.

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

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

telephony.incoming, telephony.complete, telephony.tool
web.incoming, web.complete, web.tool
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"]

حقول الطلب

الحقل	النوع	مطلوب	الوصف
`label`	string	نعم	1–120 حرفًا
`url`	string	نعم	عنوان URL عبر HTTPS (يُسمح بـ `http` فقط لـ `localhost` / `127.0.0.1`)
`events`	array	لا	الاشتراك الفارغ/المحذوف يشترك في جميع الأحداث. يجب استخدام القيم المدرجة في أنواع الأحداث الصالحة؛ وتُزال التكرارات

يعيد 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"
}

يُعاد secret عند الإنشاء فقط. تتضمن استجابات GET اللاحقة secret_hint فقط. انسخ القيمة الكاملة إلى مدير الأسرار لديك قبل إغلاق الاستجابة.

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

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"]
  }'

الحقل	النوع	الوصف
`label`	string
`url`	string
`events`	array
`status`	string	`active` أو `disabled`. اضبط `active` لإعادة تفعيل نقطة نهاية وضع الخادم عليها علامة `failing`

يعيد 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 فورًا؛ ويتم التخلي عن عمليات إعادة المحاولة قيد التنفيذ.

ذو صلة

كتالوج الأحداث

القائمة الكاملة لقيم events التي يمكنك الاشتراك فيها.

نظرة عامة على خطافات الويب

التحقق من التوقيع ودلالات التسليم.

Webhooks

Function Tools

نقاط نهاية Webhook

نقاط النهاية

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

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

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

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

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

حقول الطلب

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

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

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

ذو صلة

كتالوج الأحداث

نظرة عامة على خطافات الويب

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

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

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

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

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

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

​حقول الطلب

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

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

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

​ذو صلة

كتالوج الأحداث

نظرة عامة على خطافات الويب

نقاط النهاية

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

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

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

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

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

حقول الطلب

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

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

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

ذو صلة