נקודות קצה של Webhook

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

אובייקט נקודת קצה

{
  "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	סוגי האירועים שנרשמתם אליהם (ראו ערכים תקפים). מערך ריק נרשם לכל האירועים
`status`	string	`active`, `disabled` (מושהה ידנית), או `failing` (מוגדר אוטומטית כאשר מסירה ממצה את לוח הזמנים של הניסיונות החוזרים שלה במשך 24 שעות בלי אף 2xx אחד)
`secret_hint`	string	4 התווים הראשונים ו-4 התווים האחרונים של סוד החתימה עם שלוש נקודות (`a1b2…9f0e`) — מספיק כדי להצליב עם הסוד ששמרתם מקומית בלי לחשוף את הערך המלא
`created_at`, `updated_at`	timestamp

ה-secret המלא של נקודת הקצה מוחזר פעם אחת בעת היצירה ולעולם לא שוב. שמרו אותו באופן מאובטח — אם תאבדו אותו, מחקו את נקודת הקצה וצרו אותה מחדש.

סוגי אירועים תקפים

events מאומת מול הקבוצה המדויקת הזו — ערכים שאינם ברשימה מחזירים 400. ראו קטלוג אירועים למבנה המטען של כל סוג.

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

הצגת רשימת נקודות קצה

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

מחזיר מערך של אובייקטי נקודת קצה.

יצירת נקודת קצה

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"]
  }'

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

שדות בקשה

שדה	סוג	נדרש	תיאור
`label`	מחרוזת	כן	1–120 תווים
`url`	מחרוזת	כן	כתובת URL מסוג HTTPS ‏(`http` מותר רק עבור `localhost` / `127.0.0.1`)
`events`	מערך	לא	מערך ריק או שדה שהושמט ירשמו אתכם לכל האירועים. יש להשתמש בערכים המפורטים בסוגי אירועים תקפים; כפילויות מוסרות

מחזיר 201 Created עם אובייקט נקודת הקצה וכן שדה secret נוסף ברמה העליונה המכיל את מפתח החתימה הגולמי — מחרוזת הקסדצימלית בת 48 תווים:

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

secret מוחזר רק בעת היצירה. תגובות GET עוקבות כוללות רק את secret_hint. העתיקו את הערך המלא למנהל הסודות שלכם לפני סגירת התגובה.

עדכון נקודת קצה

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"]
  }'

שדה	סוג	תיאור
`label`	מחרוזת
`url`	מחרוזת
`events`	מערך
`status`	מחרוזת	`active` או `disabled`. הגדירו `active` כדי להפעיל מחדש נקודת קצה שהשרת סימן כ-`failing`

מחזיר 200 OK עם אובייקט נקודת הקצה המעודכן.

שליחת מסירת בדיקה

שלחו אירוע webhook.test סינתטי לנקודת קצה אחת באמצעות צינור המסירה הרגיל, כולל סריאליזציית JSON קנונית, X-ThunderPhone-Signature, רישום מסירה וניהול ניסיונות חוזרים. הבדיקה מכוונת לנקודת הקצה שנבחרה ללא קשר למסנן events שלה.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

נקודת הקצה מקבלת מעטפה כגון:

{
  "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 כדי לראות את תוצאת המסירה:

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

webhook.test הוא סינתטי ולא ניתן להוסיפו למנוי events של נקודת קצה. אם הניסיון הראשון נכשל, המסירה פועלת לפי אותו לוח זמנים של ניסיונות חוזרים כמו מסירות אירועים רגילות.

מחיקת נקודת קצה

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

מחזיר 204 No Content. המסירה לכתובת ה-URL נפסקת מיד; ניסיונות חוזרים שנמצאים בתהליך נזנחים.

קשור

קטלוג אירועים

הרשימה המלאה של ערכי events שאליהם תוכלו להירשם.

סקירת webhooks

אימות חתימה וסמנטיקת מסירה.

Webhooks

Function Tools

נקודות קצה של Webhook