POST לשרת שלכם כאשר מתרחשים אירועים
במהלך שיחה — שיחה נכנסת מתחילה, שיחה מסתיימת, הרצת דירוג מסתיימת,
התראה מופעלת וכן הלאה. קיימים שני מודלי מסירה:
נקודות קצה של webhook (מומלץ)
כתובות URL מרובות, סודות לכל נקודת קצה, מסנני אירועים לכל נקודת קצה
וניסיונות חוזרים אוטומטיים.
ניהול באמצעות
GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.Webhook מדור קודם עם כתובת URL יחידה
כתובת URL אחת לכל ארגון. כולל את אירועי מחזור החיים של השיחה, לרבות
חילופי התצורה החוסמים. מנוהל ב-
GET/PUT /v1/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:
אימות חתימה
כל בקשה כוללת חתימת HMAC-SHA256 על גוף הבקשה הגולמי בכותרתX-ThunderPhone-Signature. מפתח החתימה הוא ה-secret של נקודת הקצה (או ה-secret של ה-webhook ברמת הארגון שלכם עבור מסירות מדור קודם).
שלבים
- קראו את גוף הבקשה הגולמי לפני כל ניתוח.
- חשבו את
hmac_sha256(secret, body).hexdigest(). - השוו בזמן קבוע לכותרת
X-ThunderPhone-Signature.
סמנטיקת מסירה
כללים אלה חלים על מסירות לנקודות קצה. ה-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 שניות.כתובות IP מקור
כתובות IP מקור
webhooks יוצאים מגיעים מטווח כתובות ה-IP בענן של ThunderPhone.
אם חומת האש שלכם דורשת רשימת היתרים, פנו לתמיכה ונשתף אתכם
בטווחים העדכניים.
בחירה בין webhooks ותיקים לבין webhooks מבוססי נקודות קצה
באינטגרציות חדשות, צרכו אירועים באמצעות webhooks מבוססי נקודות
קצה. השאירו (או הוסיפו) כתובת URL ותיקה רק אם אתם מגדירים שיחות
באופן דינמי בזמן המענה או משתמשים בשליחת כלים במצב webhook — חילופי
בקשה/תגובה אלה פועלים רק בנתיב הוותיק.
קשורים
קטלוג אירועים
כל סוגי האירועים והמטענים שלהם.
נקודות קצה של webhook
נהלו נקודות קצה מרובות, מסנני אירועים וסודות.
telephony.incoming / web.incoming
הבקשה החוסמת שהשרת שלכם חייב להשיב לה כדי להגדיר שיחות.
telephony.complete / web.complete
מטען לאחר השיחה עם תמליל, הקלטה ומדדים.