> ## 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 עם סודות ומסנני אירועים לכל נקודת קצה.

מערכת ה-webhooks המבוססת על נקודות קצה מאפשרת לכם לרשום **מספר**
יעדים לכל ארגון, שלכל אחד מהם סוד משלו, סטטוס משלו
ומינוי משלו לקבוצת משנה של סוגי אירועים. זהו המודל המומלץ לכל האינטגרציות החדשות.

השוו ל-[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`. ראו [קטלוג אירועים](/he/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`  | מחרוזת | כן   | 1–120 תווים                                                                                                                          |
| `url`    | מחרוזת | כן   | כתובת URL מסוג HTTPS ‏(`http` מותר רק עבור `localhost` / `127.0.0.1`)                                                                |
| `events` | מערך   | לא   | מערך ריק או שדה שהושמט ירשמו אתכם לכל האירועים. יש להשתמש בערכים המפורטים ב[סוגי אירועים תקפים](#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`  | מחרוזת |                                                                                          |
| `url`    | מחרוזת |                                                                                          |
| `events` | מערך   |                                                                                          |
| `status` | מחרוזת | `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="/he/webhooks/events">
    הרשימה המלאה של ערכי `events` שאליהם תוכלו להירשם.
  </Card>

  <Card title="סקירת webhooks" icon="bolt" href="/he/webhooks/overview">
    אימות חתימה וסמנטיקת מסירה.
  </Card>
</CardGroup>