Skip to main content
ThunderPhone שולח בקשות HTTP מסוג POST לשרת שלכם כאשר מתרחשים אירועים במהלך שיחה — שיחה נכנסת מתחילה, שיחה מסתיימת, הרצת דירוג מסתיימת, התראה מופעלת וכן הלאה. קיימים שני מודלי מסירה:

נקודות קצה של webhook (מומלץ)

כתובות URL מרובות, סודות לכל נקודת קצה, מסנני אירועים לכל נקודת קצה וניסיונות חוזרים אוטומטיים. ניהול באמצעות GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.

Webhook מדור קודם עם כתובת URL יחידה

כתובת URL אחת לכל ארגון. כולל את אירועי מחזור החיים של השיחה, לרבות חילופי התצורה החוסמים. מנוהל ב-GET/PUT /v1/webhook.
כל עשרת סוגי האירועים בקטלוג האירועים נמסרים באמצעות נקודות קצה של webhook. ששת אירועי מחזור החיים של השיחה (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) נשלחים גם אל ה-webhook מדור קודם עם כתובת URL יחידה — אם יש לכם גם כתובת מדור קודם וגם נקודת קצה תואמת, תקבלו את האירוע בשני הנתיבים. ההתנהגות החוסמת (חילופי התצורה של telephony.incoming / web.incoming ושליחת כלים במצב webhook) מתקיימת אך ורק בנתיב המדור הקודם; כל מסירה לנקודת קצה היא התראה ללא המתנה לתגובה.

פורמט המטען

מסירות לנקודות קצה הן אובייקט JSON עם data, event_id ו-type:
event_id ייחודי לכל אירוע שנפלט. הוא זהה בין ניסיונות חוזרים וגם בין כל נקודת קצה שמקבלת את האירוע — בצעו ביטול כפילויות לפיו. ה-webhook מדור קודם עם כתובת URL יחידה שולח את אותם type ו-data, אך ללא event_id:
בהעברה ברשת, כל גוף מסודר באופן קנוני — המפתחות ממוינים בסדר אלפביתי, ללא רווחים וב-UTF-8. הדוגמאות המעוצבות במסמכים אלה מיועדות לקריאות בלבד. עיינו בקטלוג האירועים לקבלת הרשימה המלאה של סוגי האירועים ושדות המטען.

אימות חתימה

כל בקשה כוללת חתימת HMAC-SHA256 על גוף הבקשה הגולמי בכותרת X-ThunderPhone-Signature. מפתח החתימה הוא ה-secret של נקודת הקצה (או ה-secret של ה-webhook ברמת הארגון שלכם עבור מסירות מדור קודם).

שלבים

  1. קראו את גוף הבקשה הגולמי לפני כל ניתוח.
  2. חשבו את hmac_sha256(secret, body).hexdigest().
  3. השוו בזמן קבוע לכותרת X-ThunderPhone-Signature.
אנו חותמים בדיוק על הבתים שאנו משדרים, ובתים אלה הם הסריאליזציה הקנונית של JSON (מפתחות ממוינים, מפרידים קומפקטיים). לכן אימות מול הגוף הגולמי תמיד עובד — ואם המסגרת שלכם מספקת לכם רק JSON מנותח, סריאליזציה מחדש שלו עם מפתחות ממוינים ומפרידים קומפקטיים מפיקה בתים זהים. שתי השיטות מתועדות במדריך האימות.

סמנטיקת מסירה

כללים אלה חלים על מסירות לנקודות קצה. ה-webhook הוותיק עם כתובת URL יחידה מבצע ניסיון סינכרוני יחיד ללא ניסיונות חוזרים.
כל אירוע נשלח פעם אחת באופן מיידי. כל תגובת 2xx מאשרת את המסירה. בכל תוצאה אחרת (שאינה 2xx, שגיאת חיבור, פסק זמן), ננסה שוב דקה, 5 דקות, 30 דקות, שעתיים, 6 שעות, 12 שעות ו-24 שעות לאחר הניסיון הראשון — 8 ניסיונות בפריסה על פני 24 שעות. אם כל הניסיונות נכשלים, המסירה נפסקת ונקודת הקצה מסומנת כ-status="failing" בנקודות קצה של webhook. החזירו 2xx מיד כשהמטען התקבל באופן עמיד; עבדו אותו באופן אסינכרוני.
סדר המסירה הוא על בסיס מיטב המאמץ. בפועל, אנו מוסרים אירועים לפי הסדר שבו הם נפלטים, אך ניסיונות חוזרים עשויים לשנות את הסדר במקרה של כשל. תמיד הסירו כפילויות ובצעו התאמה לפי call_id / מזהה אובייקט.
המסירה היא לפחות פעם אחת: ניסיון חוזר לאחר תגובה שלא התקבלה אצלנו יכול ליצור כפילות של אירוע. כל ניסיון חוזר נושא את אותו event_id, לכן אחסנו מזהים שעובדו ודלגו על חזרות. event_id גם משותף בין נקודות קצה — שתי נקודות קצה שמנויות לאותו אירוע מקבלות את אותו event_id.
למסירות לנקודות קצה יש פסק זמן של 30 שניות לכל ניסיון. בנתיב הוותיק, בקשות חוסמות שמנהלות התנהגות של שיחה חיה — חילופי תצורה של telephony.incoming / web.incoming — מסתיימות בפסק זמן לאחר 10 שניות, אך תגובה איטית מעכבת את המענה לשיחה, לכן שאפו להשיב בתוך כמה שניות. שליחת כלים במצב webhook מאפשרת 20 שניות.
webhooks יוצאים מגיעים מטווח כתובות ה-IP בענן של ThunderPhone. אם חומת האש שלכם דורשת רשימת היתרים, פנו לתמיכה ונשתף אתכם בטווחים העדכניים.

בחירה בין webhooks ותיקים לבין webhooks מבוססי נקודות קצה

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

קשורים

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

כל סוגי האירועים והמטענים שלהם.

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

נהלו נקודות קצה מרובות, מסנני אירועים וסודות.

telephony.incoming / web.incoming

הבקשה החוסמת שהשרת שלכם חייב להשיב לה כדי להגדיר שיחות.

telephony.complete / web.complete

מטען לאחר השיחה עם תמליל, הקלטה ומדדים.