Webhooks

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

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

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

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

נקודות קצה#

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

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

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

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

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• 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"]

שדות הבקשה#

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

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

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

קשור#