> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# نقاط نهاية Webhook

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

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

قارنه بـ[خطاف الويب القديم ذي عنوان URL الواحد](/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}/test` | `admin+`      | إرسال تسليم اختبار موقّع                     |

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

```json theme={null}
{
  "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 | أنواع الأحداث المشترَك بها (راجع [القيم الصالحة](#valid-event-types)). تشترك المصفوفة الفارغة في جميع الأحداث                                             |
| `status`                   | string          | `active` أو `disabled` (متوقف يدويًا) أو `failing` (يُعيّن تلقائيًا عندما يستنفد تسليمٌ جدول إعادة المحاولة البالغ 24 ساعة دون الحصول على أي استجابة 2xx) |
| `secret_hint`              | string          | أول 4 وآخر 4 أحرف من سر التوقيع مع علامة حذف (`a1b2…9f0e`) — تكفي لمطابقة السر الذي حفظته محليًا دون كشف القيمة الكاملة                                   |
| `created_at`, `updated_at` | timestamp       |                                                                                                                                                           |

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

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

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

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

***

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

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

يعيد مصفوفة من [كائنات نقاط النهاية](#endpoint-object).

***

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

<CodeGroup>
  ```bash cURL theme={null}
  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 theme={null}
  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`  | string | نعم   | 1–120 حرفًا                                                                                                                               |
| `url`    | string | نعم   | عنوان URL عبر HTTPS (يُسمح بـ `http` فقط لـ `localhost` / `127.0.0.1`)                                                                    |
| `events` | array  | لا    | الاشتراك الفارغ/المحذوف يشترك في جميع الأحداث. يجب استخدام القيم المدرجة في [أنواع الأحداث الصالحة](#valid-event-types)؛ وتُزال التكرارات |

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

```json theme={null}
{
  "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 theme={null}
  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`  | string |                                                                                                |
| `url`    | string |                                                                                                |
| `events` | array  |                                                                                                |
| `status` | string | `active` أو `disabled`. اضبط `active` لإعادة تفعيل نقطة نهاية وضع الخادم عليها علامة `failing` |

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

***

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

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

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

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

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

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

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

***

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

<CodeGroup>
  ```bash cURL theme={null}
  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 فورًا؛
ويتم التخلي عن عمليات إعادة المحاولة قيد التنفيذ.

***

## ذو صلة

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

  <Card title="نظرة عامة على خطافات الويب" icon="bolt" href="/ar/webhooks/overview">
    التحقق من التوقيع ودلالات التسليم.
  </Card>
</CardGroup>