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

נהלו כתובות URL מרובות של webhook עם סודות ומסנני אירועים לכל נקודת קצה.

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

השוו לוובהוק מדור קודם עם כתובת URL יחידה, שנשמר לצורך תאימות לאחור אך תומך בכתובת URL אחת בלבד לכל ארגון.

נקודות קצה#

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

{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "agent_id": 42,
  "agent_name": "Support Agent",
  "secret_hint": "a1b2…9f0e",
  "paused_at": null,
  "pause_last_error": "",
  "pause_undelivered_count": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

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

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

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received (שמור; עדיין לא נפלט)
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

ל־issue.escalated אין הקשר של סוכן והוא נמסר רק לנקודות קצה כלל-ארגוניות.

לא ניתן לבחור במפורש את voice.ready ואת voice.failed. כדי לקבל אותם, צרו נקודת קצה כלל-ארגונית עם events: []. רשימת אירועים ריקה מקבלת כל אירוע נתמך מלבד telephony.turn ו־web.turn, שיש לבחור בהם במפורש.

סטטוסים של נקודות קצה#

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

מחזיר מערך של אובייקטי נקודת קצה. העבירו ?agent_id=42 כדי להחזיר רק נקודות קצה המוגדרות עבור אותו סוכן.

נקודות קצה בהיקף סוכן#

נקודות קצה כלל-ארגוניות מקבלות כל אירוע תואם. נקודת קצה עם agent_id מקבלת רק אירועים תואמים עבור שיחות שטופלו על ידי אותו סוכן; אירועים ללא הקשר של סוכן, כגון alert.triggered, לעולם אינם מגיעים אליה. תוכלו גם ליצור ולנהל נקודות קצה אלה מתוך הקטע Webhooks בבונה הסוכנים.

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

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

שדות הבקשה#

התגובה מחזירה 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"
}

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

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

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

החלפת סוד החתימה#

החליפו את סוד החתימה של נקודת קצה, למשל אם הוא אבד או ייתכן שנחשף. עבור נקודת קצה בהיקף סוכן, תוכלו גם להשתמש בלוח הבקרה: פתחו את הקטע וובהוקים של הסוכן ובחרו יצירה מחדש של סוד בנקודת הקצה. נקודות קצה כלל-ארגוניות מוחלפות דרך ה-API.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

מחזיר 200 OK:

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}

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

שלחו אירוע webhook.test סינתטי לנקודת קצה אחת באמצעות צינור המסירה הרגיל, כולל סריאליזציית JSON קנונית, שתי כותרות החתימה, תיעוד המסירה ומעקב אחר ניסיונות חוזרים. הבדיקה ממוקדת בנקודת הקצה שנבחרה, ללא קשר למסנן 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 של נקודת קצה. אם הניסיון הראשון נכשל, ThunderPhone מנסה שוב פעם אחת לאחר כדקה ולאחר מכן מפסיק; המסירה תוצג אז עם status: "failed" תחת ניפוי מסירות. מסירת בדיקה לעולם אינה מסמנת את נקודת הקצה כ-failing.

כדי להגדיר טריגר בהתאם למבנה של אירוע אמיתי, העבירו event_type אופציונלי. המסירה עדיין סינתטית ומכילה "sample": true; דוגמאות הקשורות לשיחות משתמשות ב-call_id: 0 וב-agent_id: 0.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'

event_type מקבל כל ערך מתוך סוגי אירועים תקפים. השמטתו משמרת את ההתנהגות הכללית של webhook.test.

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

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

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

ניפוי מסירות#

לפני שתסיקו שוובהוק לא נשלח, בדקו את GET /v1/developer/webhook-deliveries. הוא מציג ניסיונות אחרונים משתי מערכות הוובהוקים, כולל מזהה השיחה, מקור כתובת ה-URL, סטטוס HTTP, מספר ניסיונות, קטגוריית כשל מרשימת ההיתרים וזמן הניסיון החוזר הבא. הוא לעולם אינו מחזיר את מטען האירוע, התמליל, טקסט השגיאה השמור, גוף התגובה או נתיב כתובת ה-URL.

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

עבור 404 של n8n, ודאו תחילה שתהליך העבודה פעיל, מקבל POST, ומשתמש בכתובת ה-URL של וובהוק הייצור ולא בכתובת ה-URL של הבדיקה. 401 או 403 מצביעים על אימות או אימות חתימה; פסקי זמן מצביעים על זמן תגובה או זמינות של היעד; שגיאות TLS מצביעות על שרשרת האישורים, שם המארח או תוקף האישור.

קשור#