Webhooks API

Webhooks מאפשרים לפלטפורמה להודיע למערכות האחרות שלך ברגע שמשהו קורה — איש קשר חדש, תשובה, פגישה שנקבעה ועוד. API זה מנהל את ה-מנויים עצמם: אילו כתובות URL מקבלות אילו אירועים. למידע על אופן הקבלה והאימות של ה-payloads שה-endpoint שלך מקבל, ראה Webhooks.

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

https://api.youraiconnector.com/v1

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

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

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

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

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

רשימת מנויים

GET /webhooks

cURL

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

JavaScript

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

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.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) ברמת המנוי, ושניהם כבויים אלא אם תפעיל אותם. ראה מטענים חתומים ו-ניסיונות חוזרים.

apply_to_sub_accounts הוא אפשרות ההצטרפות לירושת סוכנות — ראו מנוי אחד לכל חשבונות הלקוחות. כבוי כברירת מחדל, ואינו פעיל בחשבונות שאין להם חשבונות לקוחות.

enabled הוא מתג ההפעלה/כיבוי של המנוי — ראו כיבוי מנוי. מנויים כבויים עדיין מופיעים ברשימה כאן.

סוד החתימה עצמו לעולם אינו כלול כאן — קרא אותו מתוך GET /webhooks/{id}/signing-secret.

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

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

GET /webhooks/events

cURL

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

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

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. נקודת קצה זו היא הרשימה המוסמכת בכל רגע נתון — קראו אותה בשידור חי במקום להטמיע את השמות בקוד (hard-coding).

יצירת מנוי

POST /webhooks

שדה	נדרש	תיאור
`url`	כן	כתובת HTTPS שתקבל את ה-payloads של האירועים דרך `POST`. חייבת להיות נגישה לציבור.
`subscribed_to`	כן	מערך לא ריק של שמות אירועים (ראו `/webhooks/events`).
`name`	לא	שם תצוגה. ניתן לשימוש גם כ-`{webhookId}` מאוחר יותר. ברירת המחדל היא שם עם חותמת זמן.
`subscribed_to_tags`	לא	מזהי תגיות המצמצמים אילו תגיות יפיקו התראת סיכום שיחה. זה לא מגביל את אירועי המנוי לתגיות אלו — כדי לקבל בקשה כאשר מוחלת תגית ספציפית, הגדירו כתובת webhook על אותה תגית בלשונית תגיות של הסוכן (או הקמפיין).
`retries_enabled`	לא	בוליאני, ברירת המחדל היא `false`. הצטרפות ל-ניסיונות חוזרים של משלוחים שנכשלו.
`generate_signing_secret`	לא	בוליאני, ברירת המחדל היא `false`. יצירת סוד חתימה מסוג HMAC עם המנוי. הסוד מוחזר פעם אחת, כ-`signing_secret` ברמה העליונה בתגובה.
`enabled`	לא	בוליאני, ברירת המחדל היא `true`. העבירו `false` כדי ליצור את המנוי כשהוא כבוי. ראו כיבוי מנוי.
`apply_to_sub_accounts`	לא	בוליאני, ברירת המחדל היא `false`. בחשבון סוכנות, `true` גורם למנוי זה לקבל גם אירועים מכל חשבון לקוח — ראו מנוי אחד לכל חשבונות הלקוחות.

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

cURL

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

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

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()

תגובה

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

עדכון מנוי לעולם אינו משבש את סוד החתימה שלו — נהל זאת דרך נתיבי סוד החתימה.

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

cURL

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

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

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()

תגובה

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

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

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

import requests

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

תגובה

{
  "success": true
}

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

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

POST /webhooks/{webhookId}/test

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

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

cURL

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

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

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()

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

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

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

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

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

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

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks/0/health",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.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

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

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

import requests

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

תגובה

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

כיבוי מנוי

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

# 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 — כך תוכלו למצוא אותם כדי להפעילם מחדש.
ניסיון חוזר שתוזמן לפני הכיבוי לא יתחדש: הניסיון החוזר קורא מחדש את המנוי בזמן השליחה ומבוטל אם המנוי כבוי.
שום דבר שלא נשלח בזמן שהמנוי היה כבוי לא ישוחזר לאחר הפעלתו מחדש.

שונה מהשבתה אוטומטית לאחר כשלים חוזרים, המדווחת על ידי GET /webhooks/{id}/health כ-is_disabled ומנוקה באמצעות POST /webhooks/{id}/reenable. enabled הוא המתג של החשבון; is_disabled הוא שלנו. אף אחד מהם לא גובר על השני — מנוי חייב להיות גם מופעל וגם לא מושבת אוטומטית כדי לבצע משלוחים.

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

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

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 מזהה את החשבון שבו האירוע התרחש בפועל, כך שהמקבל שלכם יכול לנתב לפי לקוח.
הגדרות המנוי של הסוכנות חלות בכל מקום. רשימת האירועים שלו, סוד החתימה וההצטרפות ל-ניסיונות חוזרים משמשים גם עבור המשלוחים שעברו בירושה.
מנוי עצמאי של חשבון לקוח לאותה כתובת גובר. אם לחשבון לקוח יש מנוי משלו המצביע על אותה כתובת, הוא זה שישמש עבור אירועי אותו חשבון — אותו אירוע לעולם לא יישלח פעמיים לאותה נקודת קצה.
חשבונות לקוחות לא רואים זאת. מנויים שעברו בירושה אינם מופיעים ברשימת ה-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).

ראה מטענים חתומים לדוגמאות אימות מלאות ב-Node וב-Python.

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

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

GET /webhooks/{id}/signing-secret

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

תגובה

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

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

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

תגובה

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

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

תגובה

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

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

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

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

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 סופרים משלוח שלם, לא כל ניסיון בנפרד: כשל נרשם רק לאחר שכל הניסיונות החוזרים מוצו, לכן הפעלת ניסיונות חוזרים לא תגרום להפעלה מוקדמת יותר של מנגנון ההשבתה האוטומטי.

שגיאות

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

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

מקרים נפוצים: URL שאינו מורשה, subscribed_to ריק/לא תקין, או שדות חסרים מחזירים 400; מזהה או שם לא ידועים מחזירים 404; ו-403 פירושו ש-webhooks אינם מופעלים עבור החשבון שלך. ראה שגיאות לרשימה המלאה.

צעדים הבאים

Webhooks (קבלת מטען) — הגדר את המקלט שלך והבן את מבנה המטען.
אימות — ארבע הדרכים לאימות בקשה.
שגיאות ומגבלות קצב — קודי סטטוס והמגבלה של 300 בקשות לדקה.

Webhooks API #

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

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

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

יצירת מנוי #

עדכון מנוי #

מחיקת מנוי #

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

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

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

כיבוי מנוי #

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

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

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

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

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

כיבוי חתימה #

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

שגיאות #

צעדים הבאים #

Webhooks API

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

רשימת מנויים

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

יצירת מנוי

עדכון מנוי

מחיקת מנוי

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

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

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

כיבוי מנוי

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

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

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

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

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

כיבוי חתימה

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

שגיאות

צעדים הבאים