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

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

قارنه بـ[الويب هوك القديم أحادي الرابط](/api-reference/organizations#legacy-single-url-webhook)،
المُحتفَظ به للتوافق مع الإصدارات السابقة، ولكنه يدعم رابط 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}/rotate-secret` | `admin+` | استبدال سر التوقيع |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | إرسال تسليم اختبار موقّع |
| `GET` | `/v1/developer/webhook-deliveries` | `admin+` | فحص نتائج تسليم نقاط النهاية الحديثة والقديمة |

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

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

| الحقل | النوع | الوصف |
|-------|------|-------------|
| `id` | UUID | معرّف نقطة النهاية |
| `label` | سلسلة نصية | اسم العرض، من 1 إلى 120 حرفًا |
| `url` | سلسلة نصية | عنوان URL عبر HTTPS؛ يُسمح بـ `http://localhost` للتطوير |
| `events` | مصفوفة من السلاسل النصية | أنواع الأحداث المشترَك فيها (راجع [القيم الصالحة](#valid-event-types)). تشترك المصفوفة الفارغة في جميع الأحداث باستثناء أحداث كل دور التي تتطلب اشتراكًا صريحًا (`telephony.turn` / `web.turn`) |
| `status` | سلسلة نصية | `active` أو `disabled` (موقوف يدويًا) أو `failing` (يُضبط تلقائيًا عندما تستنفد عملية تسليم جدول إعادة المحاولة لمدة 24 ساعة دون استجابة 2xx واحدة) |
| `agent_id` | عدد صحيح \| null | الوكيل الذي تقتصر عليه نقطة النهاية؛ تعني `null` على مستوى المؤسسة |
| `agent_name` | سلسلة نصية \| null | اسم الوكيل المقيّد به، أو `null` لنقطة نهاية على مستوى المؤسسة |
| `secret_hint` | سلسلة نصية | أول 4 أحرف وآخر 4 أحرف من سر التوقيع مع علامة حذف (`a1b2…9f0e`) — تكفي لمطابقة السر الذي حفظته محليًا دون كشف القيمة الكاملة |
| `paused_at` | طابع زمني \| null | وقت تعيين ThunderPhone لنقطة النهاية إلى `failing`. تكون `null` عندما تكون `active` أو `disabled` |
| `pause_last_error` | سلسلة نصية | آخر خطأ في التسليم عند إيقاف نقطة النهاية، مثل `HTTP 503: Service Unavailable`. فارغ ما لم تكن `failing` |
| `pause_undelivered_count` | عدد صحيح \| null | الأحداث التي لم تُسلَّم منذ آخر تسليم ناجح لنقطة النهاية، والمحتسبة عند إيقافها |
| `created_at`, `updated_at` | طابع زمني | |

<Note>
  يتم إرجاع `secret` الكامل لنقطة النهاية **مرة واحدة** عند الإنشاء،
  ولا يُرجع مجددًا. خزّنه بأمان — إذا فقدته،
  [دوّره](#rotate-the-signing-secret) للحصول على واحد جديد.
</Note>

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

يُتحقق من `events` مقابل هذه المجموعة الدقيقة — تُرجع القيم خارج القائمة
`400`. راجع [كتالوج الأحداث](/ar/webhooks/events) للاطلاع على بنية
الحمولة لكل نوع.

- `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`؛
  تستأنف عمليات التسليم التي لم ينتهِ جدول إعادة محاولاتها بعد من حيث
  توقفت.

---

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

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

يُرجع مصفوفة من [كائنات نقاط النهاية](#endpoint-object).
مرّر `?agent_id=42` لإرجاع نقاط النهاية المقيَّدة بذلك الوكيل فقط.

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

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

---

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

<CodeGroup>
```bash cURL
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"]
  }'
```

```python Python
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"]
```
</CodeGroup>

### حقول الطلب

| الحقل | النوع | مطلوب | الوصف |
|-------|------|----------|-------------|
| `label` | سلسلة نصية | نعم | 1–120 حرفًا |
| `url` | سلسلة نصية | نعم | عنوان URL عبر HTTPS (يُسمح بـ `http` فقط لـ `localhost` / `127.0.0.1`) |
| `events` | مصفوفة | لا | الاشتراك الفارغ أو المحذوف يشترك في جميع الأحداث باستثناء `telephony.turn` / `web.turn`، اللذين يتطلبان اشتراكًا صريحًا. يجب استخدام القيم المدرجة في [أنواع الأحداث الصالحة](#valid-event-types)؛ وتُزال القيم المكررة |
| `agent_id` | عدد صحيح \| null | لا | قيّد التسليم بوكيل ضمن هذه المؤسسة؛ احذف الحقل أو استخدم `null` لنقطة نهاية على مستوى المؤسسة |

يعيد `201 Created` مع [كائن نقطة النهاية](#endpoint-object) المحدّث، بالإضافة إلى
حقل `secret` إضافي في المستوى الأعلى يحتوي على مفتاح التوقيع الخام، وهو
سلسلة سداسية عشرية من 48 حرفًا:

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

<Warning>
  يُعاد `secret` **عند الإنشاء فقط**. تتضمن استجابات `GET` اللاحقة
  `secret_hint` فقط. انسخ القيمة الكاملة إلى مدير الأسرار لديك
  قبل تجاهل الاستجابة.
</Warning>

---

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

<CodeGroup>
```bash cURL
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"]
  }'
```
</CodeGroup>

| الحقل | النوع | الوصف |
|-------|------|-------------|
| `label` | سلسلة نصية | |
| `url` | سلسلة نصية | |
| `events` | مصفوفة | |
| `status` | سلسلة نصية | `active` أو `disabled`. اضبط `active` لإعادة تفعيل نقطة نهاية وضع الخادم علامتها `failing` |
| `agent_id` | عدد صحيح \| null | اضبط معرّف وكيل لتقييد نقطة النهاية، أو `null` لجعلها على مستوى المؤسسة |

يعيد `200 OK` مع [كائن نقطة النهاية](#endpoint-object) المحدّث.

---

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

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

<CodeGroup>
```bash cURL
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 '{}'
```
</CodeGroup>

| الحقل | النوع | مطلوب | الوصف |
|-------|------|----------|-------------|
| `include_copies` | منطقي | لا | القيمة الافتراضية هي `true`. يمنح السر الجديد أيضاً لنقاط النهاية الأخرى التابعة لمؤسستك التي لها عنوان URL نفسه والسر الحالي نفسه، مثل نسخ نقطة النهاية هذه لدى وكلاء آخرين، لكي يستمر مستقبِل واحد في التحقق باستخدام سر واحد |

يعيد `200 OK`:

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

| الحقل | النوع | الوصف |
|-------|------|-------------|
| `endpoint` | كائن | [كائن نقطة النهاية](#endpoint-object) مع `secret_hint` الجديد |
| `secret` | سلسلة نصية | سر التوقيع الجديد. يُعاد في هذه الاستجابة فقط |
| `rotated_endpoint_ids` | مصفوفة من UUID | كل نقطة نهاية تستخدم الآن السر الجديد |

<Warning>
  يتوقف استخدام السر القديم فوراً: يُوقَّع التسليم التالي،
  بما في ذلك عمليات إعادة المحاولة، بالسر الجديد. إلى أن يحصل مستقبِلك على
  السر الجديد، تفشل عمليات التسليم في فحص التوقيع؛ وإذا استجاب لها
  بحالة غير 2xx، تُعاد محاولتها وفق الجدول المعتاد البالغ 24 ساعة،
  لذا حدّث المستقبِل فوراً. إذا كان مستقبِلك يُنشر على مراحل،
  فاجعله يقبل كلا السرّين أثناء النشر — تقبل مساعدات التحقق في SDK
  قائمة من الأسرار (راجع
  [التحقق من توقيعات خطافات الويب](/ar/guides/verify-webhook-signatures)).
</Warning>

---

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

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

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

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

```json
{
  "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`
لمعرفة نتيجة التسليم:

```json
{
  "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"`
ضمن [تصحيح أخطاء عمليات التسليم](#debug-deliveries). لا يؤدي التسليم الاختباري أبدًا إلى وضع علامة `failing`
على نقطة النهاية.

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

```bash
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` أي قيمة من [أنواع الأحداث الصالحة](#valid-event-types).
يؤدي حذفه إلى الحفاظ على سلوك `webhook.test` العام.

---

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

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

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

---

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

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

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

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

---

## ذو صلة

<CardGroup cols={2}>
  <Card title="كتالوج الأحداث" icon="list" href="/ar/webhooks/events">
    القائمة الكاملة لقيم `events` التي يمكنك الاشتراك فيها.
  </Card>
  <Card title="نظرة عامة على ويبهوك" icon="bolt" href="/ar/webhooks/overview">
    التحقق من التوقيع ودلالات التسليم.
  </Card>
</CardGroup>