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

מה זה Webhook?

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

דוגמה קלאסית: אתם עובדים עם מערכת לניהול קשרי לקוחות (CRM) ורוצים שכל שיחה במספר הוירטואלי שלכם תופיע בה כרשומה. מגדירים Webhook שנשלח אל ה-CRM בסיום כל שיחה - וכל יומן השיחות "מוזרק" למערכת שלכם אוטומטית.

רשימת האוטומציות באיזור האישי: שלוש אוטומציות Webhook פעילות - תחילת שיחה, קבלת SMS וסיום עיבוד AI

ה-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 }} טופס עריכת האוטומציה: שיטת בקשה POST, כתובת יעד, סוג תוכן application/json וגוף בקשה עם משתנים משובצים

אימות ואבטחה

  • כתובת ה-Webhook חייבת להיות מאובטחת ב-https.
  • בהגדרת האוטומציה אפשר להוסיף אימות לבקשה: Bearer token (נשלח ב-Header בשם Authorization) או מפתח API ב-Header מותאם (אתם קובעים את שם ה-Header ואת הערך). הסוד נשמר אצלנו בנפרד, לא מוצג חזרה במסכים ולא נרשם ביומנים.
  • אל תסתמכו על סינון לפי כתובת IP. הבקשות נשלחות מתשתית שליחה מנוהלת וכתובות המקור שלה עשויות להשתנות ללא התראה. הדרך הנכונה לוודא שהבקשה הגיעה מאיתנו היא ה-Header של האימות שהגדרתם.

אמינות: ניסיונות חוזרים והשבתה אוטומטית

  • בקשה נחשבת מוצלחת כשהשרת שלכם מחזיר קוד תגובה 2xx. גוף התגובה שלכם אינו נקרא ואינו נשמר - רק קוד התגובה נבדק. בקשה שלא נענית בזמן המוקצב נחשבת ככשלון.
  • בקשה שנכשלת עוברת ניסיונות חוזרים אוטומטיים במרווחים הולכים וגדלים.
  • אחרי 3 כשלונות סופיים רצופים (כלומר: גם הניסיונות החוזרים מוצו) האוטומציה מושבתת אוטומטית ונשלח אליכם מייל עם פרטי התקלה. אחרי שתיקנתם את הצד שלכם, מפעילים מחדש בלחיצה על "הפעלה מחדש" במסך האוטומציות.
  • לכל אוטומציה יש יומן פעילות במסך האוטומציות, שבו רואים את הבקשות האחרונות, קודי התגובה והשגיאות.

קובץ הקלטת השיחה

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

  1. אחזור הקובץ ב-API - קריאה למתודת /calls/recording/ מחזירה את קובץ ההקלטה עצמו כתגובת HTTP. זו השיטה המומלצת: אין בה בשום שלב URL ציבורי. תיעוד ה-API
  2. URL חתום וזמני בתוך ה-Webhook - מוסיפים לכתובת ה-Webhook שלכם פרמטר config[ttl] עם זמן תפוגה בדקות (מקסימום 10), ומשבצים בגוף בקשת ה-POST את השדה "recording": {}. בזמן השליחה השדה יוחלף באובייקט עם URL חתום וזמני לקובץ ההקלטה. למשל: https://www.example.com/hook?config[ttl]=2 - ה-URL שיתקבל יפעל למשך 2 דקות בלבד, מספיק לאוטומציה שלכם להוריד את הקובץ, ואז ייחסם מעצמו.
  3. הפקת URL חתום ב-API - קריאה למתודת /calls/get-recording-urls/ עם זמן תפוגה בדקות מחזירה URL זמני לקובץ.

צירוף מידע משלכם (Custom Data)

כמו בכל בקשת HTTP, פרמטרים שתוסיפו בעצמכם לכתובת ה-URL - למשל https://www.example.com/hook?my_id=12345 - "יחזרו" אליכם בכל בקשה ותוכלו לחלץ אותם בצד שלכם. זו הדרך לקשר את הבקשה למזהה פנימי במערכת שלכם.

בצעו בדיקות עם Webhook.site

לפני שמחברים את ה-Webhook למערכת האמיתית שלכם, נוח לבדוק אותו מול שירות Webhook.site: הוא מפיק כתובת URL ייחודית, שומר כל בקשה שמגיעה אליה ומציג אותה בפניכם. כך תבצעו את הבדיקה:

  1. היכנסו אל Webhook.site - אין צורך בהרשמה, כתובת ייחודית מופקת אוטומטית עם הכניסה.
  2. הדביקו את הכתובת שהופקה בשדה כתובת ה-URL של האוטומציה ושמרו.
  3. בצעו שיחת ניסיון אל המספר שלכם באקסטרה.
  4. חזרו אל Webhook.site ובחנו את הבקשה שהגיעה מהשרת שלנו: הכתובת, ה-Headers והגוף - בדיוק כפי שבניתם אותם, אחרי החלפת המשתנים בערכים האמיתיים של השיחה.

כשהתוצאה נראית לכם, החליפו את הכתובת בכתובת האמיתית של המערכת שלכם.