אף אחד לא אוהב לעבוד קשה, ואם הטכנולוגיה יכולה לעשות בשבילנו את העבודה השחורה - למה לא לנצל את זה? Webhook הוא בדיוק הכלי הזה: מנגנון אוטומטי שמדווח למערכות שלכם על כל שיחה, מסביב לשעון, בלי התערבות יד אדם.
מה זה Webhook?
Webhook הוא מנגנון שמוזנק בעת התרחשות של אירוע: כאשר משהו קורה - למשל מסתיימת שיחה בקו שלכם - המערכת שלנו שולחת בקשת HTTP לכתובת URL שהגדרתם, עם המידע על השיחה: מספר הטלפון של הצד השני, משך השיחה, מועד השיחה ועוד.
דוגמה קלאסית: אתם עובדים עם מערכת לניהול קשרי לקוחות (CRM) ורוצים שכל שיחה במספר הוירטואלי שלכם תופיע בה כרשומה. מגדירים Webhook שנשלח אל ה-CRM בסיום כל שיחה - וכל יומן השיחות "מוזרק" למערכת שלכם אוטומטית.
ה-Webhooks הם חלק ממערכת האוטומציות
Webhooks מוגדרים ומנוהלים במסך האוטומציות באיזור האישי. כל Webhook הוא אוטומציה: בוחרים אירוע (טריגר) בשירות מסוים, ומגדירים פעולה מסוג "בקשת HTTP".
העיקרון המרכזי: אתם בונים את הבקשה. אתם מרכיבים את כתובת ה-URL ואת גוף הבקשה בעצמכם, ומשבצים בהם משתנים של השיחה בדיוק איפה שנוח לכם. כך הבקשה מגיעה בדיוק בפורמט שהמערכת שלכם (או שירותים כמו Make ו-Zapier וכל endpoint אחר) מצפה לקבל.
האירועים הזמינים
לכל שירות האירועים שלו:
- תחילת שיחה - במספר הוירטואלי ובנתב השיחות הוירטואלי.
- סיום שיחה - בכל השירותים: קו סלולרי, סופטפון, מספר וירטואלי ונתב שיחות.
- קבלת SMS - במספר הוירטואלי ובנתב השיחות הוירטואלי, כשמתקבל מסרון במספר.
- סיום עיבוד AI - מוזנק כשעיבוד Genie AI של השיחה (תמלול, סיכום) מסתיים. האירוע זמין לכולם, אבל מכיוון שבמנוי Genie AI Pro העיבוד מופעל אוטומטית בסיום כל שיחה, הוא שימושי בעיקר למנויי Pro.
באירוע תחילת שיחה, מטבע הדברים, אין עדיין נתונים כמו משך שיחה או מועד סיום - המשתנים האלה זמינים רק באירוע סיום שיחה. נתוני ה-AI (תקציר, סיכום) זמינים רק באירוע סיום עיבוד AI.
בניית הבקשה
בהגדרת האוטומציה תבחרו ותרכיבו:
- שיטת הבקשה: GET או POST. אנחנו ממליצים על POST: המידע על שיחה הולך וגדל עם השנים - עיבוד ה-AI למשל מוסיף סיכומים ותקצירים - וגוף בקשה מכיל אותו בנוח, בעוד Query String של GET מוגבל באורכו.
- כתובת ה-URL: חייבת להיות בסכימת https. אפשר לשלב בה משתנים.
- Content-Type (בבקשת POST):
application/json,application/x-www-form-urlencodedאוmultipart/form-data. - גוף הבקשה (Body) (בבקשת POST): טקסט חופשי שאתם כותבים - לרוב JSON - עם משתנים משובצים.
משתנים
בכל מקום בכתובת או בגוף הבקשה אפשר לשבץ משתנה בתחביר {{ שם המשתנה }}. בזמן השליחה כל משתנה מוחלף בערך שלו מהשיחה. הרשימה המלאה של המשתנים הזמינים - שמשתנה לפי האירוע שבחרתם - מוצגת בטופס ההקמה והעריכה של האוטומציה, לצד הסבר קצר על כל משתנה. אפשר גם לעיין ברשימה המלאה מראש, לפי כל אירוע, במדריך המשתנים המלא.
דוגמה לגוף בקשת POST בפורמט JSON:
{
"id": "{{ id }}",
"event": "{{ event }}",
"type": "{{ type }}",
"caller": "{{ numbers.caller.e164 }}",
"duration": "{{ duration }}",
"time_start": "{{ time.start }}"
}
שימו לב: שמות המפתחות (משמאל לנקודתיים) הם לבחירתכם החופשית - רק מה שבתוך {{ }} חייב להיות שם משתנה מהרשימה שבטופס.
ובבקשת GET משבצים את המשתנים ישירות בכתובת:
https://www.example.com/calls?my_id=12345&call={{ id }}&caller={{ numbers.caller.e164 }}&event={{ event }} 
אימות ואבטחה
- כתובת ה-Webhook חייבת להיות מאובטחת ב-https.
- בהגדרת האוטומציה אפשר להוסיף אימות לבקשה: Bearer token (נשלח ב-Header בשם Authorization) או מפתח API ב-Header מותאם (אתם קובעים את שם ה-Header ואת הערך). הסוד נשמר אצלנו בנפרד, לא מוצג חזרה במסכים ולא נרשם ביומנים.
- אל תסתמכו על סינון לפי כתובת IP. הבקשות נשלחות מתשתית שליחה מנוהלת וכתובות המקור שלה עשויות להשתנות ללא התראה. הדרך הנכונה לוודא שהבקשה הגיעה מאיתנו היא ה-Header של האימות שהגדרתם.
אמינות: ניסיונות חוזרים והשבתה אוטומטית
- בקשה נחשבת מוצלחת כשהשרת שלכם מחזיר קוד תגובה 2xx. גוף התגובה שלכם אינו נקרא ואינו נשמר - רק קוד התגובה נבדק. בקשה שלא נענית בזמן המוקצב נחשבת ככשלון.
- בקשה שנכשלת עוברת ניסיונות חוזרים אוטומטיים במרווחים הולכים וגדלים.
- אחרי 3 כשלונות סופיים רצופים (כלומר: גם הניסיונות החוזרים מוצו) האוטומציה מושבתת אוטומטית ונשלח אליכם מייל עם פרטי התקלה. אחרי שתיקנתם את הצד שלכם, מפעילים מחדש בלחיצה על "הפעלה מחדש" במסך האוטומציות.
- לכל אוטומציה יש יומן פעילות במסך האוטומציות, שבו רואים את הבקשות האחרונות, קודי התגובה והשגיאות.
קובץ הקלטת השיחה
הקלטת שיחה היא מידע רגיש, ולכן איננו מייצרים לה URL ציבורי קבוע כברירת מחדל. יש שלוש דרכים לקבל את ההקלטה:
- אחזור הקובץ ב-API - קריאה למתודת
/calls/recording/מחזירה את קובץ ההקלטה עצמו כתגובת HTTP. זו השיטה המומלצת: אין בה בשום שלב URL ציבורי. תיעוד ה-API - קישור להקלטה בתוך ה-Webhook - במסך עריכת האוטומציה, באירועים שכוללים הקלטה (סיום שיחה וסיום עיבוד AI), בחרו בשדה קישור להקלטת השיחה את תוקף הקישור: קישור זמני של עד 10 דקות - מספיק לאוטומציה שלכם להוריד את הקובץ, ואז הקישור נחסם מעצמו - או קישור ציבורי קבוע (שימו לב: הקלטה עם קישור קבוע זמינה לכל מי שמחזיק בקישור, ללא הגבלת זמן). הקישור מגיע במשתנה
{{ recording }}- אובייקט עם הקישור (url) והתוקף (ttl) - לשיבוץ בגוף הבקשה או בכתובת. - הפקת URL חתום ב-API - קריאה למתודת
/calls/get-recording-urls/עם זמן תפוגה בדקות מחזירה URL זמני לקובץ.
בצעו בדיקות עם Webhook.site
לפני שמחברים את ה-Webhook למערכת האמיתית שלכם, נוח לבדוק אותו מול שירות Webhook.site: הוא מפיק כתובת URL ייחודית, שומר כל בקשה שמגיעה אליה ומציג אותה בפניכם. כך תבצעו את הבדיקה:
- היכנסו אל Webhook.site - אין צורך בהרשמה, כתובת ייחודית מופקת אוטומטית עם הכניסה.
- הדביקו את הכתובת שהופקה בשדה כתובת ה-URL של האוטומציה ושמרו.
- בצעו שיחת ניסיון אל המספר שלכם באקסטרה.
- חזרו אל Webhook.site ובחנו את הבקשה שהגיעה מהשרת שלנו: הכתובת, ה-Headers והגוף - בדיוק כפי שבניתם אותם, אחרי החלפת המשתנים בערכים האמיתיים של השיחה.
כשהתוצאה נראית לכם, החליפו את הכתובת בכתובת האמיתית של המערכת שלכם.
שאלות נפוצות
-
היכן במערכת אוכל להגדיר את הוובהוק?
במסך ההגדרות של השירות, בהתאם לשירות.
בקו הסלולרי: באזור האישי > קווי סלולר > קליק על המספר שבעבורו רוצים להגדיר ואז תחת כותרת "Webhook למתכנתים".
במספר הוירטואלי: באזור האישי > מספרים וירטואליים > אייקון 3 נקודות לצד המספר שבעבורו רוצים להגדיר > הגדרות, ושם להגדיר תחת "Webhook למתכנתים".
בנתב הוירטואלי: באזור האישי > נתב וירטואלי > אייקון 3 נקודות לצד המספר שבעבורו רוצים להגדיר > הגדרות, ושם להגדיר תחת "Webhook למתכנתים".
-
למה חלק מהמידע חסר בבקשת GET?
בקשות מסוג GET מוגבלות בכמות המידע שאפשר להעביר בהן. בשל הריבוי במידע על השיחה הכולל גם אובייקט AI למשל, עשויים לכלול טקסט רב. כדי לקבל את כל המידע על השיחה, בחרו בקריאת POST.
