# Webhooks API

Webhooks מאפשרים לפלטפורמה להודיע למערכות האחרות שלך ברגע שמשהו קורה — איש קשר חדש, תשובה, פגישה שנקבעה ועוד. API זה מנהל את ה-**מנויים** עצמם: אילו כתובות URL מקבלות אילו אירועים. למידע על אופן הקבלה והאימות של ה-payloads שה-endpoint שלך מקבל, ראה [Webhooks](../integrations/webhooks.md).

כל הנתיבים להלן יחסיים לכתובת ה-URL הבסיסית של ה-API:

```
https://api.youraiconnector.com/v1
```

כל בקשה חייבת לעבור אימות. ראה [Authentication](authentication.md) עבור ארבע השיטות המקובלות. הדוגמאות כאן משתמשות ב-header מסוג `X-API-Key` (וטופס פרמטר שאילתה אחד עבור cURL).

::: note
**הערה:** יש להפעיל Webhooks עבור החשבון שלך. אם הם אינם מופעלים, נקודות קצה אלו יחזירו `403`.
:::


---

## כיצד ממוענים מנויים

לכל מנוי יש `id` ו-`name` אופציונלי. ניתן להשתמש בכל אחד מהם כ-`{webhookId}` בנתיב עבור עדכון, מחיקה, בדיקה, תקינות והפעלה מחדש.

> **עדיף להשתמש בשם.** מזהי מנויים הם תלויי מיקום, לכן הם עלולים להשתנות לאחר מחיקת מנוי אחר. אם תגדיר `name` יציב בעת יצירת מנוי, פנה אליו לפי שם כדי להימנע מהפתעות.

---

## רשימת מנויים

`GET /webhooks`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/webhooks?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "webhooks": [
    {
      "id": "0",
      "name": "Order updates hook",
      "url": "https://hooks.example.com/incoming",
      "subscribed_to": ["Contact Created", "Replies"],
      "subscribed_to_tags": [],
      "created_at": "2026-06-09T12:00:00.000Z",
      "signing_enabled": true,
      "signing_secret_created_at": "2026-07-15T09:30:00.000Z",
      "retries_enabled": true,
      "enabled": true,
      "apply_to_sub_accounts": false
    }
  ]
}
```

`signing_enabled` ו-`retries_enabled` הם אפשרויות בחירה (opt-in) ברמת המנוי, ושניהם כבויים אלא אם תפעיל אותם. ראה [מטענים חתומים](#signed-payloads) ו-[ניסיונות חוזרים](#retries).

`apply_to_sub_accounts` הוא אפשרות ההצטרפות לירושת סוכנות — ראו [מנוי אחד לכל חשבונות הלקוחות](#one-subscription-for-all-client-accounts-agencies). כבוי כברירת מחדל, ואינו פעיל בחשבונות שאין להם חשבונות לקוחות.

`enabled` הוא מתג ההפעלה/כיבוי של המנוי — ראו [כיבוי מנוי](#switching-a-subscription-off). מנויים כבויים עדיין מופיעים ברשימה כאן.

סוד החתימה עצמו לעולם אינו כלול כאן — קרא אותו מתוך [`GET /webhooks/{id}/signing-secret`](#read-the-signing-secret).

---

## רשימת סוגי אירועים הניתנים להרשמה

מחזיר את המחרוזות המדויקות שבהן ניתן להשתמש ב-`subscribed_to`. השתמש בזה כדי לגלות שמות אירועים חוקיים במקום להטמיע אותם בקוד (hard-coding).

`GET /webhooks/events`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/webhooks/events" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/events", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks/events",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**תגובה**

התגובה היא `{"success": true, "events": [...]}`, כאשר `events` מכיל כעת 22 מחרוזות מדויקות: Contact Created, Human Alerted, Appointment Booked, Replies, Reads, Deliveries, Credits Spent, Credits Recharged, Low Credit Balance, Contact Paused, Contact Do Not Disturb, Contact Unarchived, New Message, Contact Resumed, Chat Concluded, Task Created, Task Updated, Task Completed, Daily Summary Created, Channel Connected, Broadcast Started, ו-Broadcast Completed (הערך Channel Connected מתקבל ב-`subscribed_to` אך שום דבר לא מפיק אותו כיום, לכן אל תבסס עליו פיתוח).

למידע על המשמעות של כל אירוע וקוד ה-`event` שהוא שולח ב-payload, ראו [22 אירועי ה-Webhook](../integrations/webhooks.md#the-22-webhook-events). נקודת קצה זו היא הרשימה המוסמכת בכל רגע נתון — קראו אותה בשידור חי במקום להטמיע את השמות בקוד (hard-coding).

---

## יצירת מנוי

`POST /webhooks`

| שדה | נדרש | תיאור |
|---|---|---|
| `url` | כן | כתובת HTTPS שתקבל את ה-payloads של האירועים דרך `POST`. חייבת להיות נגישה לציבור. |
| `subscribed_to` | כן | מערך לא ריק של שמות אירועים (ראו `/webhooks/events`). |
| `name` | לא | שם תצוגה. ניתן לשימוש גם כ-`{webhookId}` מאוחר יותר. ברירת המחדל היא שם עם חותמת זמן. |
| `subscribed_to_tags` | לא | מזהי תגיות המצמצמים אילו תגיות יפיקו התראת סיכום שיחה. זה לא מגביל את אירועי המנוי לתגיות אלו — כדי לקבל בקשה כאשר מוחלת תגית ספציפית, הגדירו כתובת webhook על אותה תגית בלשונית **תגיות** של הסוכן (או הקמפיין). |
| `retries_enabled` | לא | בוליאני, ברירת המחדל היא `false`. הצטרפות ל-[ניסיונות חוזרים](#retries) של משלוחים שנכשלו. |
| `generate_signing_secret` | לא | בוליאני, ברירת המחדל היא `false`. יצירת [סוד חתימה](#signed-payloads) מסוג HMAC עם המנוי. הסוד מוחזר פעם אחת, כ-`signing_secret` ברמה העליונה בתגובה. |
| `enabled` | לא | בוליאני, ברירת המחדל היא `true`. העבירו `false` כדי ליצור את המנוי כשהוא כבוי. ראו [כיבוי מנוי](#switching-a-subscription-off). |
| `apply_to_sub_accounts` | לא | בוליאני, ברירת המחדל היא `false`. בחשבון סוכנות, `true` גורם למנוי זה לקבל גם אירועים מכל חשבון לקוח — ראו [מנוי אחד לכל חשבונות הלקוחות](#one-subscription-for-all-client-accounts-agencies). |

> **כללי URL:** ה-URL חייב להשתמש ב-`https://` ולהיות נגיש לציבור. כתובות `http://` רגילות, `localhost`, כתובות רשת פרטית וכתובות פנימיות של הפלטפורמה יידחו עם `400`.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/webhooks?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "name": "Order updates hook"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://hooks.example.com/incoming",
    subscribed_to: ["Contact Created", "Replies"],
    name: "Order updates hook",
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://hooks.example.com/incoming",
        "subscribed_to": ["Contact Created", "Replies"],
        "name": "Order updates hook",
    },
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "webhook_id": "1",
  "webhook": {
    "id": "1",
    "name": "Order updates hook",
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}
```

---

## עדכון מנוי

ספקו לפחות אחד מ-`url`, `subscribed_to`, `name`, `subscribed_to_tags`, `retries_enabled`, `enabled` או `apply_to_sub_accounts`. שדות שיושמטו ישמרו על ערכיהם הנוכחיים. `subscribed_to` ו-`subscribed_to_tags` הם החלפות, לא מיזוגים.

`PUT /webhooks/{webhookId}`

> עדכון מנוי לעולם אינו משבש את סוד החתימה שלו — נהל זאת דרך [נתיבי סוד החתימה](#signed-payloads).

> כאשר ה-URL משתנה, המשלוח עבור ה-URL החדש מופעל מחדש באופן אוטומטי, מה שנותן לנקודת קצה שנכשלה בעבר התחלה חדשה.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/Order%20updates%20hook" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/v2/incoming",
    "subscribed_to": ["Replies", "Chat Concluded"]
  }'
```

**JavaScript**

```javascript
const res = await fetch(
  `https://api.youraiconnector.com/v1/webhooks/${encodeURIComponent("Order updates hook")}`,
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://hooks.example.com/v2/incoming",
      subscribed_to: ["Replies", "Chat Concluded"],
    }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/webhooks/Order updates hook",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://hooks.example.com/v2/incoming",
        "subscribed_to": ["Replies", "Chat Concluded"],
    },
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "webhook_id": "0",
  "webhook": {
    "id": "0",
    "name": "Order updates hook",
    "url": "https://hooks.example.com/v2/incoming",
    "subscribed_to": ["Replies", "Chat Concluded"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}
```

מזהה או שם לא ידוע יחזירו `404` עם `{ "success": false, "error": "Webhook not found" }`.

---

## מחיקת מנוי

מסיר את המנוי כך שה-URL שלו יפסיק לקבל מטעני אירועים. מונים של תקינות המשלוח מתאפסים, כך שהוספה מחדש של אותו URL מאוחר יותר תתחיל עם רשומה נקייה.

`DELETE /webhooks/{webhookId}`

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/webhooks/0",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true
}
```

---

## שליחת מטען בדיקה

שולח מטען לדוגמה ל-URL של המנוי כדי שתוכלו לאמת את המקלט שלכם מקצה לקצה. ניתן להעביר באופן אופציונלי `event` כדי לשלוט בסוג האירוע שהדוגמה מדמה. משלוחי בדיקה לעולם אינם משפיעים על מוני התקינות של המנוי.

`POST /webhooks/{webhookId}/test`

התגובה תמיד מחזירה `200` ומדווחת על התוצאה עם דגל `delivered` — בדיקה שנכשלה **לא** מחזירה סטטוס שגיאה. כאשר `delivered` הוא `false`, התגובה כוללת את פרטי הכישלון.

| שדה | נדרש | תיאור |
|---|---|---|
| `event` | לא | סוג אירוע לסימולציה (חייב להיות אחד מ-`/webhooks/events`). ברירת המחדל היא אירוע משלוח. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/test?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event": "Contact Created" }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/test", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ event: "Contact Created" }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks/0/test",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"event": "Contact Created"},
)
data = res.json()
```

**תגובה** (נמסרה)

```json
{
  "success": true,
  "webhook_id": "0",
  "delivered": true
}
```

**תגובה** (נכשלה)

```json
{
  "success": true,
  "webhook_id": "0",
  "delivered": false,
  "failure_type": "permanent",
  "status_code": 404,
  "error_message": "Request failed with status code 404"
}
```

`failure_type` הוא אחד מ-`permanent`, `temporary`, `timeout`, `network` או `unknown`.

---

## בדיקת תקינות משלוח

מחזיר את רשומת תקינות המשלוח עבור ה-URL של המנוי: כמה משלוחים הצליחו וכמה נכשלו, האם המשלוח מושהה כרגע לאחר כשלים חוזרים, ופרטי הכשל האחרון. מחזיר `"health": null` כאשר טרם בוצעו ניסיונות משלוח.

`GET /webhooks/{webhookId}/health`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/webhooks/0/health" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/health", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks/0/health",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "webhook_id": "0",
  "url": "https://hooks.example.com/incoming",
  "health": {
    "consecutive_failures": 0,
    "total_failures": 2,
    "total_successes": 120,
    "is_disabled": false,
    "disabled_at": null,
    "disabled_reason": null,
    "last_failure": null,
    "last_success_at": "2026-06-09T12:00:00.000Z",
    "created_at": "2026-05-01T08:00:00.000Z",
    "updated_at": "2026-06-09T12:00:00.000Z"
  }
}
```

כאשר `is_disabled` הוא `true`, המשלוח ל-URL הושהה אוטומטית לאחר כשלים חוזרים. תקן את המקלט שלך ולאחר מכן הפעל אותו מחדש (להלן).

---

## הפעלה מחדש של משלוח

מחדש את המשלוח עבור webhook שה-URL שלו הושהה אוטומטית לאחר כשלים חוזרים. פעולה זו מאפסת את דגל ההשהיה ואת מוני הכשלים אך **אינה** מבצעת ניסיון משלוח — השתמש בנקודת הקצה לבדיקה לאחר מכן כדי לוודא שהמקלט שלך תקין שוב.

`POST /webhooks/{webhookId}/reenable`

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/reenable?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/reenable", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks/0/reenable",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "webhook_id": "0"
}
```

---

## כיבוי מנוי

`enabled` הוא מתג ההפעלה/כיבוי של המנוי עצמו. כיבויו עוצר את המשלוחים תוך שמירה על ה-URL, רשימת האירועים וסוד החתימה ללא שינוי.

```bash
# Off
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Back on
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

- **היעדר ערך משמעו מופעל.** מנוי שנוצר לפני ששדה זה היה קיים אינו כולל ערך `enabled` שמור והוא מבצע משלוחים כרגיל. `GET /webhooks` תמיד מדווח על ערך בוליאני קונקרטי.
- מנויים כבויים **עדיין מופיעים** ברשימה של `GET /webhooks` — כך תוכלו למצוא אותם כדי להפעילם מחדש.
- [ניסיון חוזר](#retries) שתוזמן לפני הכיבוי לא יתחדש: הניסיון החוזר קורא מחדש את המנוי בזמן השליחה ומבוטל אם המנוי כבוי.
- שום דבר שלא נשלח בזמן שהמנוי היה כבוי לא ישוחזר לאחר הפעלתו מחדש.

> שונה מהשבתה אוטומטית לאחר כשלים חוזרים, המדווחת על ידי [`GET /webhooks/{id}/health`](#check-delivery-health) כ-`is_disabled` ומנוקה באמצעות [`POST /webhooks/{id}/reenable`](#re-enable-delivery). `enabled` הוא המתג של החשבון; `is_disabled` הוא שלנו. אף אחד מהם לא גובר על השני — מנוי חייב להיות גם מופעל וגם לא מושבת אוטומטית כדי לבצע משלוחים.

---

## מנוי אחד לכל חשבונות הלקוחות (סוכנויות)

בחשבון סוכנות, הגדירו `apply_to_sub_accounts: true` על מנוי (בעת היצירה או דרך `PUT`) והוא יקבל גם אירועים המתרחשים בכל אחד מחשבונות הלקוחות של הסוכנות — נקודת קצה אחת מכסה את כל הסוכנות, במקום ליצור מחדש את המנוי בכל חשבון לקוח.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apply_to_sub_accounts": true}'
```

כיצד זה פועל:

- **בלוק ה-`user` מבדיל בין החשבונות.** בלוק ה-`user` של כל payload מזהה את החשבון שבו האירוע התרחש בפועל, כך שהמקבל שלכם יכול לנתב לפי לקוח.
- **הגדרות המנוי של הסוכנות חלות בכל מקום.** רשימת האירועים שלו, [סוד החתימה](#signed-payloads) וההצטרפות ל-[ניסיונות חוזרים](#retries) משמשים גם עבור המשלוחים שעברו בירושה.
- **מנוי עצמאי של חשבון לקוח לאותה כתובת גובר.** אם לחשבון לקוח יש מנוי משלו המצביע על אותה כתובת, הוא זה שישמש עבור אירועי אותו חשבון — אותו אירוע לעולם לא יישלח פעמיים לאותה נקודת קצה.
- **חשבונות לקוחות לא רואים זאת.** מנויים שעברו בירושה אינם מופיעים ברשימת ה-webhook של חשבון הלקוח, והלקוח אינו יכול לכבות אותם — רק הסוכנות מנהלת אותם.
- **תקינות המשלוח מנוטרת לכל חשבון לקוח.** נקודת קצה שממשיכה להיכשל מושבתת אוטומטית עבור החשבון שהמשלוחים שלו נכשלו, לא עבור כל הסוכנות.
- **`subscribed_to_tags` אינו עובר בירושה.** רשימת התגיות מתייחסת לתגיות של הסוכנות עצמה, שאינן קיימות בחשבונות הלקוחות — צמצום סיכום השיחה חל רק על האירועים של הסוכנות עצמה.
- **לא פעיל במקומות אחרים.** בחשבון ללא חשבונות לקוחות, הדגל נשמר כראוי ואינו מבצע דבר.

---

## כותרות בכל משלוח

שלוש כותרות אלו נשלחות בכל משלוח, ללא קשר לשאלה אם המנוי חתום או לא:

| כותרת | משמעות |
|---|---|
| `X-Webhook-Delivery` | מזהה יציב עבור האירוע הלוגי. זהה לאורך ניסיונות חוזרים — בצעו דה-דופליקציה לפיו. |
| `X-Webhook-Attempt` | מספר ניסיון (מתחיל ב-1). |
| `X-Webhook-Event` | שם האירוע. |

---

## מטענים חתומים

חתימה היא אופציונלית, כבויה כברירת מחדל, ומוגדרת לכל מנוי בנפרד. כאשר למנוי יש סוד חתימה, כל משלוח נושא שתי כותרות נוספות מעבר לשלוש שנשלחות בכל משלוח (`X-Webhook-Delivery`, `X-Webhook-Attempt` ו-`X-Webhook-Event`):

| כותרת | משמעות |
|---|---|
| `X-Webhook-Signature` | `v1=<hex>` — HMAC-SHA256 של המחרוזת `"<timestamp>.<raw request body>"`, עם מפתח המבוסס על סוד החתימה של ה-webhook שאתם יוצרים ומחליפים ב-`GET/POST/DELETE /v1/webhooks/{webhookId}/signing-secret`. |
| `X-Webhook-Timestamp` | זמן שליחה, בשניות Unix. כרוך בתוך החתימה, כך שלא ניתן לשנותו באופן עצמאי. |

כדי לאמת, חשבו מחדש את ה-HMAC-SHA256 על גוף הבקשה הגולמי (raw body) עם הסוד שלכם והשוו אותו לכותרת. בצעו את האימות מול גוף הבקשה ה**גולמי**. סריאליזציה מחדש של JSON שעבר פענוח משנה את הבתים ושוברת את ההשוואה. דחו משלוחים שחותמת הזמן שלהם נמצאת מחוץ לחלון רעננות (300 שניות היא ברירת מחדל סבירה) כדי למנוע התקפות שידור חוזר (replay), והשוו באמצעות פונקציה בטוחה לתזמון (timing-safe).

ראה [מטענים חתומים](../integrations/webhooks.md#signed-payloads-verifying-a-webhook-really-came-from-us) לדוגמאות אימות מלאות ב-Node וב-Python.

> **חתימה אינה זהה לאימות API.** ה-REST API עצמו מאומת באמצעות מפתחות API ולא OAuth (אמנם קיים OAuth 2.1 עבור שרתי MCP שאתם רושמים ככלי בוט), ועדיין אין חבילות SDK רשמיות ב-npm או ב-PyPI — קראו לנקודות הקצה עם כל לקוח HTTP.

### קרא את סוד החתימה

`GET /webhooks/{id}/signing-secret`

```bash
curl "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": true,
  "signing_secret": "whsec_1a2b3c...",
  "signing_secret_created_at": "2026-07-15T09:30:00.000Z"
}
```

כאשר החתימה כבויה, `signing_enabled` הוא `false` ו-`signing_secret` הוא `null`.

### צור או רענן את סוד החתימה

`POST /webhooks/{id}/signing-secret`

יוצר סוד (ומפעיל חתימה) או מחליף את הקיים. מחזיר את הסוד החדש.

```bash
curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": true,
  "signing_secret": "whsec_9f8e7d...",
  "signing_secret_created_at": "2026-07-15T10:00:00.000Z"
}
```

החלפת הסוד נכנסת לתוקף באופן מיידי — המשלוח הבא ייחתם באמצעות הסוד החדש בלבד. מומלץ לקבל את שני הסודות לזמן קצר בזמן שאתה פורס את השינוי לנקודת קצה פעילה.

ניתן גם ליצור סוד בעת היצירה על ידי העברת `"generate_signing_secret": true` ל-`POST /webhooks`; התגובה תכלול אז שדה `signing_secret` ברמה העליונה.

### כיבוי חתימה

`DELETE /webhooks/{id}/signing-secret`

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": false
}
```

> כל שלושת נתיבי סודות החתימה דורשים הרשאת **עריכה** (edit) של אינטגרציות, כולל `GET` — הסוד הוא פרט אימות שיכול לזייף משלוחים, לכן הוא אינו חשוף לתפקידים בעלי הרשאת קריאה בלבד.

---

## ניסיונות חוזרים

אופציונלי, כבוי כברירת מחדל, ומוגדר לכל מנוי באמצעות הערך הבוליאני `retries_enabled` ב-`POST /webhooks` או ב-`PUT /webhooks/{id}`.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"retries_enabled": true}'
```

כאשר האפשרות מופעלת, משלוח שנכשל ינוסה שוב לאחר **דקה אחת, 5 דקות, 30 דקות ושעתיים** מהניסיון הראשון (סה"כ כיסוי של כשעתיים ו-40 דקות).

- **ניסיון חוזר:** תגובות 5xx, פסקי זמן (timeouts) וכשלי חיבור.
- **ללא ניסיון חוזר:** כל תגובת 4xx. המקבל דוחה את הבקשה עצמה, לכן שליחתה שוב ללא שינוי רק תשחזר את הדחייה.

ניסיונות חוזרים הופכים משלוח כפול לאפשרי — נקודת קצה שעיבדה אירוע אך פג תוקפה לפני שהספיקה להשיב, תראה אותו שוב. בצע ביטול כפילויות לפי `X-Webhook-Delivery`, שנשאר קבוע לאורך כל הניסיונות. זו הסיבה שניסיונות חוזרים הם אופציונליים.

המונים של [delivery-health](#check-delivery-health) סופרים משלוח שלם, לא כל ניסיון בנפרד: כשל נרשם רק לאחר שכל הניסיונות החוזרים מוצו, לכן הפעלת ניסיונות חוזרים לא תגרום להפעלה מוקדמת יותר של מנגנון ההשבתה האוטומטי.

---

## שגיאות

כל השגיאות משתמשות במעטפת הסטנדרטית:

```json
{
  "success": false,
  "error": "Webhook not found"
}
```

מקרים נפוצים: URL שאינו מורשה, `subscribed_to` ריק/לא תקין, או שדות חסרים מחזירים `400`; מזהה או שם לא ידועים מחזירים `404`; ו-`403` פירושו ש-webhooks אינם מופעלים עבור החשבון שלך. ראה [שגיאות](errors-and-pagination.md) לרשימה המלאה.

---

## צעדים הבאים

- [Webhooks (קבלת מטען)](../integrations/webhooks.md) — הגדר את המקלט שלך והבן את מבנה המטען.
- [אימות](authentication.md) — ארבע הדרכים לאימות בקשה.
- [שגיאות ומגבלות קצב](errors-and-pagination.md) — קודי סטטוס והמגבלה של 300 בקשות לדקה.