Webhooks #

Webhooks מאפשרים ל-Your AI Connector להודיע באופן אוטומטי לכלי העבודה האחרים שלך בכל פעם שמשהו חשוב קורה — יצירת איש קשר חדש, קביעת פגישה, או קבלת הודעה. במקום לבדוק עדכונים באופן ידני, המערכות המחוברות שלך מקבלות התראה מיידית ברגע שמשהו קורה.

מהם Webhooks? #

חשוב על Webhook כעל הודעת טקסט אוטומטית בין שתי אפליקציות. כאשר משהו קורה ב-Your AI Connector (כמו הרשמה של איש קשר חדש), הפלטפורמה שולחת התראה מיידית למערכת אחרת לבחירתך. עליך לספק כתובת אינטרנט (הנקראת “כתובת URL של Webhook”) שאליה יישלחו התראות אלו — כתובת זו מסופקת בדרך כלל על ידי ה-CRM שלך, פלטפורמת האוטומציה או המפתח שלך.

דף ה-Webhooks שולח נתונים מחוץ ל-Your AI Connector בלבד. ה-Webhooks שמוגדרים כאן פועלים בכיוון אחד, מ-Your AI Connector אל הכלים האחרים שלך. כדי להכניס ליד חדש או נתונים אחרים פנימה (מטופס באתר, מה-CRM שלך או מ-GoHighLevel), עומדות בפניך שתי אפשרויות. אוטומציה עם טריגר Webhook מספקת לך כתובת אינטרנט שאליה הטופס או הכלי שלך יכולים לשלוח נתונים, והשלבים שלה יכולים לאחר מכן ליצור את איש הקשר, לשלוח הודעה ועוד. לחלופין, המערכת שלך יכולה לבצע קריאת API, למשל פעולת Create a Contact, באמצעות מפתח ה-API שלך; ראה גישת API ו-משפכים.

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

שימושים נפוצים כוללים:

• סנכרון אנשי קשר חדשים ל-CRM שלך.
• הפעלת תהליך עבודה ב-Zapier, Make או Pabbly כאשר מוחלת תגית.
• התראה לצוות שלך ב-Slack כאשר אדם נדרש להתערבות.
• עדכון מערכת היומן שלך כאשר נקבעת פגישה.
• רישום סיכומי שיחות למסד הנתונים שלך.

הגדרת Webhooks #

1. בסרגל הצד השמאלי, לחץ על Settings (סמל גלגל השיניים).
2. בסרגל הצד של ההגדרות, תחת קבוצת Integrations, לחץ על Webhooks.

בחשבון שבו עדיין לא הוגדרו Webhooks, הדף נראה כך:

3. לחץ על New webhook (Webhook חדש), בפינה הימנית העליונה. טופס ייפתח בתוך הדף:

4. מלא את הפרטים:
   • כתובת URL של נקודת קצה (Endpoint URL) — כתובת האינטרנט שאליה Your AI Connector תשלח התראות על אירועים. תקבל אותה מהמערכת החיצונית שלך (CRM, פלטפורמת אוטומציה או שרת מותאם אישית).
   • שם — תווית שתזהה מאוחר יותר (למשל “התראות Slack” או “סנכרון CRM”). לשימושך האישי בלבד.

כתובת ה-Webhook שלך חייבת להיות כתובת https:// נגישה לציבור. כתובות http:// פשוטות, כתובות localhost או כתובות רשת פנימיות נדחות בעת השמירה. כדי לבדוק מהמחשב שלך, השתמש במנהרה ציבורית (webhook.site או ngrok) במקום ב-localhost.

5. תחת אירועים (Events), לחץ על האירועים שברצונך ש-webhook זה יקבל — כל 24 האירועים מפורטים ב-24 אירועי ה-Webhook.
6. (אופציונלי) הפעל את נסה שוב משלוחים שנכשלו (Retry failed deliveries) אם ברצונך ש-Your AI Connector ימשיך לנסות במקרה של כשל זמני — ראה ניסיון חוזר של משלוחים שנכשלו.
7. לחץ על צור webhook. הוא יופיע ברשימה מתחת לטופס, ותוכל ללחוץ על בדיקה (Test) בשורה שלו בכל עת כדי לשלוח מטען (payload) לדוגמה לנקודת הקצה שלך.

נדרשת הרשאה. הוספה, עריכה או בדיקה של Webhooks דורשות הרשאת “עריכה” (edit) של Integrations (חברי צוות בעלי הרשאת צפייה בלבד יראו הודעת קריאה בלבד במקום הטופס).

חתימה על Webhook מחייבת שהוא כבר יהיה שמור — פתח שורה של Webhook קיים כדי לערוך אותו, ולוח ה-Signing secret יופיע בתחתית טופס העריכה. לטיוטה חדשה לגמרי שלא נשמרה עדיין אין אפשרות חתימה — עיין ב-מטענים חתומים להלן.

Webhook אחד עבור כל חשבונות הלקוחות שלך (סוכנויות) #

אם אתה מנהל סוכנות, אינך צריך ליצור מחדש את אותו ה-webhook בכל חשבון לקוח. בחשבון הסוכנות, לטופס ה-webhook יש מתג נוסף: Also fire for all client accounts. הפעל אותו, וה-webhook הזה יקבל גם אירועים המתרחשים בכל חשבון לקוח תחת הסוכנות שלך — נקודת קצה אחת, כל הסוכנות.

כיצד זה פועל:

• הבלוק user מציין לאיזה לקוח שייך האירוע. כל התראה כבר נושאת בלוק user המזהה את החשבון שבו התרחש האירוע, כך שהאוטומציה שלך יכולה לנתב לפי לקוח.
• הגדרות ה-webhook שלך חלות בכל מקום. האירועים שבחרת, סוד החתימה והגדרת הניסיון החוזר משמשים גם עבור משלוחים לחשבונות לקוחות.
• אין משלוחים כפולים. אם לחשבון לקוח יש webhook משלו המצביע על אותה כתובת URL, הוא זה שישמש עבור אירועי אותו חשבון — אותו אירוע לעולם לא יגיע פעמיים לאותה נקודת קצה.
• הלקוחות לא רואים זאת. ה-webhook אינו מופיע בדף ה-Webhooks של חשבון הלקוח, והלקוחות אינם יכולים לכבות אותו — הוא מנוהל על ידך בלבד.
• האמינות מנוטרת לפי חשבון לקוח. אם נקודת הקצה שלך ממשיכה להיכשל, היא תכובה אוטומטית עבור החשבון שהמשלוחים שלו נכשלו (ראה אמינות Webhook), ולא עבור כל הסוכנות בבת אחת.

המתג מופיע רק בחשבונות סוכנות. הגדרתו דרך ה-API נתמכת גם היא — ראה את השדה apply_to_sub_accounts ב-Webhooks API.

אירועי הפעלה זמינים #

באפשרותך להפעיל או להשבית כל אחד מ-24 אירועי ה-webhook באופן עצמאי. כאשר אירוע מופעל, Your AI Connector שולח התראה לכתובת ה-webhook שלך עם הנתונים הרלוונטיים. כל אירוע, משמעותו, וקוד ה-event שהוא מציב במטען מפורטים יחד ב-24 אירועי ה-Webhook בהמשך דף זה.

כדאי לדעת: משימה נוצרה (Task Created), משימה עודכנה (Task Updated), ו-משימה הושלמה (Task Completed) ניתנים לבחירה מלאה ונשמרים כראוי. סיכום יומי נוצר (Daily Summary Created) הוא גם תוספת חדשה. ראה Webhook של משימה הושלמה להלן עבור מבנה המטען הזה.

טריגרים של Webhook מבוססי תגיות #

subscribed_to_tags אינו מגדיר את אירועי ה-webhook לפי תגית. הוא רק מצמצם אילו תגיות יפיקו התראה על סיכום שיחה. כדי לקבל בקשה כאשר מוחלת תגית ספציפית, הגדר כתובת URL של webhook באותה תגית בלשונית תגיות (Tags) בעורך הסוכן.

לטופס ה-webhook עצמו אין בורר תגיות, לא בעת יצירת webhook חדש ולא בעת עריכתו, לכן ניתן לקרוא או לשנות את ה-subscribed_to_tags רק דרך ממשק ה-API של Webhooks, או על ידי פנייה לתמיכה.

כדאי לדעת: עריכת webhook קיים שיש לו רשימת subscribed_to_tags (שינוי שם, שינוי אירועים, החלפת מצב ניסיונות חוזרים) אינה מוחקת עוד את הרשימה הזו — מכיוון שלטופס אין בורר תגיות לשליחה חזרה, שמירה מדף זה כעת מותירה את הרשימה הקיימת ללא שינוי. (זה היה באג אמיתי לפני ה-21 ביולי 2026: שמירה מטופס ה-webhook נהגה למחוק את הרשימה מכיוון שהיא תמיד שלחה רשימת תגיות ריקה. אם webhook איבד את רשימת ה-subscribed_to_tags שלו לפני תאריך זה, יהיה צורך להגדיר אותו מחדש דרך ה-API.)

יצירת סיכום עבור אנשי קשר מתויגים #

במקום שבו ל-webhook יש רשימת subscribed_to_tags, ניתן להפעיל את צור סיכום (Generate Summary). כאשר האפשרות מופעלת, Your AI Connector מייצר באופן אוטומטי סיכום שיחה עבור איש הקשר כאשר אחת מהתגיות הללו מוחלת, וכולל אותו בנתוני ה-webhook — הקשר מלא ללא צורך בבקשה נפרדת.

בדיקת ה-Webhook שלך #

1. פתח את הגדרות ← אינטגרציות ← Webhooks.
2. בשורה של ה-webhook שלך, לחץ על בדיקה (Test).
3. בדוק במערכת החיצונית שלך כדי לוודא שהיא קיבלה את נתוני הבדיקה.
4. עיין בפורמט הנתונים כדי לוודא שהמערכת שלך מסוגלת לנתח אותו כראוי.

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

מה נחשב למשלוח מוצלח #

בין אם תלחץ על Test (בדיקה) ובין אם האירוע מופעל באמת, אנחנו שולחים את אותו הדבר:

• בקשת POST (לעולם לא GET), עם הגוף כ-JSON ו-Content-Type: application/json.
• הכותרות המפורטות תחת מטענים חתומים. כותרות חתימה נכללות רק לאחר שהגדרת סוד חתימה.

אנחנו מתייחסים למשלוח כאל מוצלח כאשר:

• נקודת הקצה שלך משיבה עם כל סטטוס 2xx (200, 201, 204 — כולם תקינים).
• היא משיבה בתוך 30 שניות.

כמה דברים שמפתיעים אנשים:

• גוף התגובה מתעלם. אין צורך להחזיר JSON ספציפי. תגובת 200 ריקה מספיקה.
• הפניות (Redirects) נחשבות ככישלון. אנחנו לא עוקבים אחריהן, לכן קוד 301 או 302 (כולל הפניה עקב לוכסן בסוף הכתובת, או מ-http ל-https) יירשם כמשלוח שנכשל. שמור את ה-URL הסופי, לא כזה שמבצע הפניה.
• מחרוזות שאילתה (Query strings) נתמכות במלואן. https://your-app.com/hook?token=abc123 נשלח בדיוק כפי ששמרת אותו, לכן הצבת אסימון במחרוזת השאילתה עובדת באותה מידה כמו הצבתו בנתיב.
• ה-URL שלך חייב להיות https:// ונגיש לציבור. כתובות השייכות לתשתית של Your AI Connector עצמה נדחות, אך נקודות הקצה שלך ב-Google Cloud Functions, Cloud Run, App Engine, Firebase Hosting או בכל מקום אחר הן תקינות.
• חומת אש או שכבת הגנה מפני בוטים לפני נקודת הקצה שלך עלולה לחסום אותנו. המקרה הנפוץ ביותר הוא Cloudflare: אם באזור שלך מופעל מצב Bot Fight Mode או אתגר מנוהל, הבקשה שלנו מקבלת דף אתגר “Just a moment…” עם קוד 403 במקום להגיע לשרת שלך — ובקשת שרת-לשרת לעולם לא תוכל לעבור אתגר דפדפן, לכן גם כפתור ה-Test וגם אירועים אמיתיים נכשלים באותה צורה. כפתור ה-Test יגיד לך מתי זה קורה (“Cloudflare is showing a bot challenge to our request”). תקן זאת ב-Cloudflare באמצעות כלל Security / WAF שמדלג על אתגרים עבור נתיב ה-webhook שלך (או עבור סוכן המשתמש Webhook-Delivery/1.0), ולאחר מכן לחץ שוב על Test.
• אם חומת האש שלך זקוקה לרשימת היתרים (allowlist) של כתובות IP במקום (למשל בתוכנית החינמית של Cloudflare, שבה לא ניתן לדלג על מצב Bot Fight Mode רגיל באמצעות כלל WAF, אך כלל גישה של IP שמוגדר כ-Allow פועל לפניו), אנחנו יכולים לעזור: כל משלוח, בין אם מכפתור ה-Test ובין אם מאירוע חי, נשלח מכתובת IPv4 קבועה אחת (ללא טווחים, ללא IPv6, ללא החלפה). צור קשר עם התמיכה ואנחנו ניתן לך את הכתובת להוספה לרשימת ההיתרים. שמור על אימות חתימה כבדיקת האמון האמיתית שלך, מכיוון שהיא מאמתת כל מטען (payload) ללא קשר למקורו.
• תוצאת ה-Test מציגה לך בדיוק מה ענתה נקודת הקצה שלך. בדיקה שנכשלה מציגה כעת את הסיבה האמיתית (סטטוס ה-HTTP שנקודת הקצה שלך החזירה, פסק זמן, או שלא הצלחנו להגיע לכתובת כלל) במקום שגיאה כללית, ובדיקה על webhook שמור נשלחת חתומה כאשר החתימה מופעלת, בדיוק כמו אירוע חי.

שימוש ב-n8n, Make או Zapier (“כתובת URL לבדיקה” לעומת “כתובת URL לייצור”) #

פלטפורמות אוטומציה בדרך כלל מספקות לך שתי כתובות webhook שונות, וזה מבלבל משתמשים רבים:

• כתובת URL לבדיקה (ב-n8n היא מכילה /webhook-test/). היא מקבלת נתונים רק בזמן שאתה צופה באופן פעיל בקנבס ולחצת זה עתה על Listen for test event (או Test workflow). היא לוכדת אירוע בודד ואז מפסיקה להאזין — לכן לחיצה על בדיקה ב-Your AI Connector מספר פעמים ברצף תתפוס רק את הראשון, ורק אם חלון ההאזנה פעיל באותו רגע בדיוק. כדי לבדוק: לחץ תחילה על Listen for test event ב-n8n, לאחר מכן חזור ל-Your AI Connector ולחץ על בדיקה פעם אחת.
• כתובת URL לייצור (ב-n8n היא מכילה /webhook/, ללא -test). זו הכתובת שיש להדביק ב-Your AI Connector עבור אירועים חיים. היא עובדת רק לאחר שה-workflow שלך מוגדר כ-Active. אם ה-workflow אינו פעיל, n8n תדחה את הבקשה עם שגיאת “404 / webhook not registered”, למרות ש-Your AI Connector שלחה את הנתונים כראוי.

בקצרה: בצע בדיקות עם כתובת ה-URL לבדיקה בזמן האזנה, אך כדי שה-webhook ימשיך לעבוד עם אנשי קשר אמיתיים, שמור את כתובת ה-URL לייצור ב-Your AI Connector וודא שזרימת העבודה מוגדרת כ-Active.

פורמט נתוני Webhook #

כאשר Webhook מופעל, Your AI Connector שולחת נתונים מובנים (JSON) לכתובת ה-Webhook שלך. אם אתה משתמש בפלטפורמת אוטומציה כמו Zapier או Make, היא מנתחת נתונים אלו עבורך באופן אוטומטי. אם אתה בונה אינטגרציה מותאמת אישית:

{
  "event": "contactCreated",
  "contact": { "id": "<contact-id>", "first_name": "Jane", "...": "..." },
  "campaign": { "id": "<campaign-id>", "name": "AI Receptionist", "status": "Live" },
  "agent": { "id": "<agent-id>", "name": "Front Desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" }
}

קרא את agent, לא את campaign. קמפיינים עברו לסוכני AI ושידורים (ראו קמפיינים עברו), לכן אנשי הקשר שלכם נמצאים אצל סוכן ו-agent מציין לכם מי מהם טיפל בשיחה. השדה campaign עדיין נשלח כדי שמקלטים ישנים ימשיכו לעבוד, אך הוא בדרך כלל null; הוא מתמלא רק עבור איש קשר שעדיין נושא קישור לקמפיין קלאסי. אל תניחו ש-campaign תמיד נמצא שם.

הבלוק agent הגיע ב-15 באוגוסט 2026. הוא מופיע לצד campaign באירועים הקשורים לשיחה — צ’אט שהסתיים, ‘נא לא להפריע’, המשך שיחה, ביטול ארכוב, השהיית AI, הודעה חדשה, סיכום שיחה, וה-webhook שניתן להגדיר על תגית — והוא נושא את ה-id וה-name של הסוכן המטפל, או null כאשר אין סוכן מעורב. זהו תוסף בלבד: כל שדה שאתה כבר מקבל נשאר ללא שינוי, כך שמקלט שבנית לפני תאריך זה ימשיך לעבוד ללא צורך בעדכון.

חלק מהאירועים מוסיפים בלוק עליון נוסף משלהם. לדוגמה, פגישה נקבעה (Appointment Booked), פגישה בוטלה (Appointment Cancelled) ו-פגישה נקבעה מחדש (Appointment Rescheduled) מוסיפים בלוק appointment (ראה Webhook של פגישה שנקבעה), הודעה חדשה (New Message) מוסיפה בלוק message מלא עם הטקסט (ראה Webhook של הודעה חדשה), ו-משלוחים (Deliveries) ו-קריאות (Reads) מוסיפים בלוק message קצר עם מזהה ההודעה והסטטוס בלבד (ראה Webhook של משלוחים וקריאות).

Deliveries ו-Reads מציינים איזו הודעה, אך לא מה היה כתוב בה. הם נושאים בלוק message המכיל את ה-id וה-status של ההודעה — וה-id הזה הוא אותו ה-messageId ש-נקודת הקצה לשליחת הודעה מחזירה, כך שתוכלו להתאים אישור מסירה או קריאה להודעה המדויקת ששלחתם — אך ללא גוף ההודעה. Replies (תשובות) אינו נושא בלוק message כלל. אם אתם זקוקים למילים שנשלחו או התקבלו, הירשמו ל-New Message לצד אירועים אלו.

שני דברים שכדאי לדעת לפני כתיבת המקלט שלך. אין שדה timestamp, ואין מעטפת data. כל בלוק יושב ברמה העליונה של אובייקט ה-JSON, כפי שמוצג לעיל.

24 אירועי ה-Webhook #

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

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

האירוע ‘ערוץ חובר’ (Channel Connected) טרם נשלח. הוא מופיע ברשימת האירועים, אך כרגע שום דבר לא מפעיל אותו. אל תבנה פונקציונליות המסתמכת עליו.

התראות מבוססות תגיות ומשימות משתמשות במבנים נפרדים משלהן. ראו Contact Tags Updated ו-Task Completed.

Webhook של איש קשר שנוצר #

נשלח כאשר אירוע יצירת איש קשר (Contact Created) מופעל (איש קשר חדש מתווסף ידנית, באמצעות ייבוא, או באמצעות API).

שם האירוע #

contactCreated

פורמט המטען (Payload) #

{
  "event": "contactCreated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null,
    "ad_attribution": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

דגימת ה-“Test” ואירוע אמיתי נראים מעט שונים. כפתור הבדיקה שולח נתוני מציין מיקום (ג’ון דו, בלוק קמפיין לדוגמה). אירוע “איש קשר נוצר” אמיתי נושא את פרטי איש הקשר בפועל, וחלק מהשדות עשויים להיות ריקים בהתאם לערוץ.

Webhook הודעה חדשה #

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

שם האירוע #

new_message

פורמט המטען (Payload) #

{
  "event": "new_message",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null,
    "ad_attribution": null
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "body": "Hi, are you open on Saturday?",
    "direction": "inbound",
    "status": "received",
    "created_at": "2026-07-30T17:27:06.000Z",
    "channel": "whatsapp_web",
    "media_url": null,
    "media_content_type": null
  }
}

עדיין אין בלוק campaign במטען זה. הודעה חדשה שולחת את contact, agent, user ו-message. הבלוק agent נוסף ב-15 באוגוסט 2026 והוא מציין לכם איזה סוכן מטפל בשיחה; אם אתם זקוקים להקשר נוסף לגבי איש הקשר, חפשו אותו דרך ה-API באמצעות contact.id.

שמור קבצים מצורפים זמן קצר לאחר הגעתם. הקישור media_url מפסיק לעבוד 7 ימים לאחר הגעת ההודעה, בכל הערוצים (WhatsApp Business API, WhatsApp Web, אינסטגרם, מסנג’ר, טלגרם, ווידג’ט צ’אט והשאר); הקובץ עצמו נשאר. כדי לקבל קישור חדש מאוחר יותר, קרא ל-הורדת קובץ מצורף של הודעה עם contacts/{contact.id}/messages/{message.id}. השדות נוספו ב-13 בספטמבר 2026.

כאשר media_url הוא null אך גוף ההודעה מציין שקובץ הגיע. מספר קבצים מצורפים מאוחסנים בצורה שאין לה קישור ישיר, ו-Reel, פוסט או אזכור בסטורי באינסטגרם ששותפו הם קישור לאינסטגרם ולא קובץ, לכן גם הם מגיעים כ-null (גוף ההודעה מציין מה שותף). עבור קובץ, קרא ל-Download a message’s attachment עם מזהה ההודעה כדי לקבל קישור.

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

רשומות AI פנימיות אינן מפעילות את ה-Webhook הזה. לצד הודעות אמיתיות, הפלטפורמה שומרת שורות רישום משלה בתוך שיחה (קריאות לכלי ה-AI ורשומות תור פנימיות). אלו לעולם לא נשלחות — אתה מקבל רק הודעות שנשלחו או התקבלו בפועל.

Deliveries and Reads Webhook #

שני אירועים אלו מדווחים מה קרה להודעה לאחר שעזבה את Your AI Connector: Deliveries מופעל כאשר הודעה מגיעה לאיש הקשר (או נכשלת), ו-Reads מופעל כאשר איש הקשר פותח אותה, בערוצים התומכים באישור קריאה.

שניהם נושאים בלוק message עם המזהה של ההודעה שהאירוע עוסק בה, כך שתוכלו להתאים את העדכון להודעה המדויקת ששלחתם.

שמות אירועים #

delivered ו-undelivered עבור Deliveries, read עבור Reads.

פורמט המטען (Payload) #

{
  "event": "delivered",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "ad_referral": null,
    "ad_attribution": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "status": "delivered"
  }
}

כיצד להתאים עדכון להודעה ששלחתם. שמרו את ה-messageId שאתם מקבלים בחזרה כשאתם שולחים הודעה דרך ה-API. כאשר מגיעה התראה על Deliveries או Reads, חפשו את המזהה השמור מול message.id ב-payload — זהו אישור המסירה או הקריאה שלכם עבור אותה הודעה מדויקת.

אין כאן טקסט הודעה. הבלוק message נושא רק את המזהה והסטטוס. הירשמו ל-New Message אם אתם זקוקים גם לגוף ההודעה.

הבלוק message קיים רק כאשר אנו יודעים איזו הודעה זו הייתה. בעדכון נדיר שאיננו יכולים לקשר להודעה שמורה, הבלוק מושמט לחלוטין במקום להישלח ריק — לכן בדקו ש-message קיים לפני קריאת message.id.

התראה אחת לכל שינוי סטטוס. הודעה יוצאת בודדת מייצרת בדרך כלל התראת delivered ולאחר מכן, בערוצים עם אישורי קריאה, התראת read. שליחה שנכשלה מייצרת undelivered במקום זאת.

Appointment Booked Webhook #

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

שם האירוע #

booked

פורמט המטען (Payload) #

{
  "event": "booked",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com"
  },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z",
    "status": "Confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": null,
    "external_reference": "crm-booking-1042",
    "event": {
      "id": "<service-id>",
      "event_name": "Intro Call",
      "slot_duration": 30,
      "location": "Zoom",
      "meeting_link": "https://...",
      "event_type": "online"
    }
  }
}

google_calendar_event_id הוא לעיתים קרובות null ב-webhook זה, וזה תקין. אירוע Google Calendar נוצר באותו רגע שבו יוצאת התראה זו, לכן המזהה בדרך כלל אינו מוכן עדיין. משוך מחדש את הפגישה לפי ה-appointment_id שלה רגע לאחר מכן אם אתה זקוק לו. הוא נשאר null לצמיתות אם לחשבון אין Google Calendar מחובר, לכן אל תמתין לו לנצח.

כפתור ה-“Test” שולח בלוק appointment לדוגמה עם ערכים מומצאים, כדי שתוכל לבנות מול המבנה לפני שתגיע פגישה אמיתית.

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

Webhooks של פגישה בוטלה ונקבעה מחדש #

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

שמות אירועים #

appointment_cancelled ו-appointment_rescheduled

פורמט המטען (Payload) #

הגוף זהה ל-פגישה נקבעה, עם הפגישה כפי שהיא לאחר השינוי. ביטול מוסיף appointment.cancelation_reason; קביעה מחדש מוסיפה בלוק previous עליון עם הזמנים הישנים:

{
  "event": "appointment_rescheduled",
  "contact": { "id": "<contact-id>", "email": "jane@example.com", "phone_number": "+15551234567", "first_name": "Jane", "last_name": "Smith" },
  "campaign": null,
  "agent": { "id": "<agent-id>", "name": "Front desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-21T09:00:00.000Z",
    "end_time": "2026-07-21T09:30:00.000Z",
    "status": "Confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": "<calendar-event-id>",
    "external_reference": "crm-booking-1042",
    "cancelation_reason": null,
    "event": { "id": "<service-id>", "event_name": "Intro Call", "slot_duration": 30 }
  },
  "previous": {
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z"
  }
}

שינוי אחד, אירוע אחד. ביטול פגישה שולח ‘פגישה בוטלה’ בלבד, גם אם הזמן שלה השתנה באותה עריכה. עריכת הכותרת, ההערות או החדר בלבד לא שולחת אף אחד מהם. הזזת אותה פגישה פעמיים שולחת שני אירועי ‘פגישה נקבעה מחדש’.

Webhook של סיום שיחה #

מופעל כאשר ה-AI מחליט ששיחה הגיעה לסיומה (בוצעה הזמנה, ליד נפסל, וכן הלאה).

שם האירוע #

chat_concluded

פורמט המטען (Payload) #

המטען נושא את event, את ה-contact המלא, את ה-agent שטיפל בצ’אט ואת ה-user של החשבון. הוא נושא גם את conversation_cost, כמה עלתה שיחה זו בקרדיטים, כך שזרימת n8n או Make יכולה לתעד זאת ללא קריאה נוספת:

{
  "event": "chat_concluded",
  "contact": { "id": "abc123", "first_name": "Jane", "channel": "whatsapp" },
  "agent": { "id": "agent_1", "name": "Sales Agent" },
  "user": { "id": "user_1" },
  "conversation_cost": {
    "credits": 7.5,
    "session_id": "sess_9f2",
    "started_at": "2026-09-26T09:14:02.000Z",
    "outcome": "contained"
  }
}

• credits: קרדיטים שחויבו בתוך שיחה זו, לאחר הפחתת החזרים. זה נספר באותה דרך כמו דוח עלויות השיחה ב-API.
• outcome: contained (ה-AI טיפל בזה לבד), handed_off (מישהו מהצוות שלכם השיב לאחר ה-AI, או שה-AI התריע בפני אדם) או no_ai.
• conversation_cost מושמט כאשר לא ניתן לחשב את הנתון באותו רגע. התייחסו אליו כאל אופציונלי.

Webhook של עדכון תגיות איש קשר #

מופעל כאשר תגית מוחלת על איש קשר, ולאותה תגית יש כתובת URL של webhook שהוגדרה בסוכן שאליו מוקצה איש הקשר.

שם האירוע #

contact_tags_updated

מתי זה מופעל #

• תג מוחל על איש קשר שמשויך אליו סוכן AI.
• לפחות אחד מהתגים המוחלים כולל כתובת URL של webhook שהוגדרה בלשונית תגים (Tags) בעורך של אותו סוכן.

איש קשר שעדיין נושא קישור לקמפיין קלאסי מלפני המעבר לסוכנים הוא מקרה מיוחד: אם התגים של אותו קמפיין כוללים כתובות URL של webhook, אלו ישמשו; אחרת, ישמשו אלו של הסוכן.

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

הסרת תגית לעולם אינה שולחת בקשה. רוב האנשים מפנים כתובות אלו לפעולה — גביית פיקדון, קביעת תור, התרעה לנציג — לכן הסרת תגית מאיש קשר בעבר הייתה מפעילה מחדש את אותה פעולה. כעת זה כבר לא אפשרי. הסרה עדיין מופיעה ב-removed_tags כאשר היא מתרחשת באותו עדכון שבו מתבצעת החלה (apply) לאותה כתובת, כך שאוטומציה שקוראת את שני המערכים שומרת על תמונה מלאה; מה שהיא לעולם לא תראה הוא בקשה שנגרמה כתוצאה מהסרה בלבד. (השתנה ב-12 באוגוסט 2026. לפני תאריך זה, הסרות שלחו בקשה גם כן.)

פורמט המטען (Payload) #

{
  "event": "contact_tags_updated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "is_bot_active": true,
    "ad_referral": {
      "ctwa_clid": "ARAbc123...",
      "source_id": "120210000000000",
      "source_type": "ad",
      "source_url": "https://fb.me/xxxx",
      "headline": "Get 20% off today",
      "body": "Message us now to claim your discount",
      "channel": "whatsapp"
    },
    "ad_attribution": null
  },
  "added_tags": ["qualified-lead"],
  "removed_tags": ["new-lead"],
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

בדיקת webhook של תגית #

לצד שדה כתובת ה-URL של ה-webhook בכרטיסיית התגיות (Tags) מופיע כפתור בדיקה (Test). הוא שולח מטען (payload) לדוגמה לכתובת ה-URL הזו באופן מיידי, כך שתוכל לוודא שהאוטומציה שלך מקבלת אותו לפני שתמתין לשיחה אמיתית.

הבדיקה שולחת את אותו מבנה contact_tags_updated המוצג לעיל, תוך שימוש באיש קשר זמני (placeholder), עם התגית שאתה בודק ב-added_tags ו-removed_tags ריק. מה שהאוטומציה שלך רואה בבדיקה הוא מה שהיא תראה בסביבת הייצור.

שני דברים שכדאי לדעת:

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

אם הבדיקה נכשלת, ההודעה תציין מה השיב ה-endpoint שלך (למשל 404 או 500), מה שבדרך כלל מספיק כדי לזהות כתובת URL שגויה או תהליך עבודה (workflow) שאינו מופעל.

Webhook של השלמת משימה #

לעיון בלבד. Webhooks של משימות (כנתונים) מתועדים כאן עבור מפתחים; האירועים משימה נוצרה, משימה עודכנה ו-משימה הושלמה ניתנים לבחירה ברשימת האירועים הסטנדרטית בטופס ה-webhook כמו כל אירוע אחר — ראה אירועי טריגר זמינים ו-24 אירועי ה-Webhook.

מטען (payload) זה נשלח כאשר משימה עוברת לשלב המסומן כשלב השלמה. משימה שעוברת בין שלבים שאינם שלבי השלמה שולחת את המבנה taskUpdated במקום זאת.

שם האירוע #

taskCompleted

מתי זה מופעל #

• משימה עודכנה.
• הערך stage שלה השתנה בהשוואה לערכו הקודם.
• השלב החדש מוגדר כשלב השלמה בהגדרות שלבי המשימות של החשבון.

פורמט המטען (Payload) #

{
  "event": "taskCompleted",
  "contact": {
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<task-id>",
    "title": "Follow up with Jane",
    "description": "Confirm pricing and send proposal",
    "type": "follow_up",
    "priority": "high",
    "stage": "<stage-id>",
    "due_date": "2026-01-20T15:00:00Z",
    "source": "ai",
    "source_detail": "<source-detail>",
    "campaign_id": "<campaign-id>",
    "linked_human_alert": "<human-alert-id>",
    "tags": ["qualified-lead"],
    "notes": "Customer requested a callback"
  }
}

כיבוי (או מחיקה) של Webhook #

לכל webhook יש מתג הפעלה/כיבוי, ממש בשורה שלו. כיבוי (OFF) של אחד מהם מפסיק את קבלת האירועים, אך שומר על כל מה שהגדרת — ה-URL, האירועים, וכל מפתח חתימה. הפעל אותו בחזרה והוא ימשיך מהמקום שבו הפסיק; שום דבר שקרה בזמן שהוא היה כבוי לא יישלח לאחר מכן.

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

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

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

מטען חתום (אימות שה-Webhook אכן הגיע מאיתנו) #

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

חתימה היא אופציונלית וכבויה כברירת מחדל, ואתה מפעיל אותה עבור כל webhook בנפרד, מתוך תצוגת העריכה של אותו webhook (פתח את השורה של webhook שמור).

הפעלת חתימה #

1. פתח את ה-webhook (הגדרות ← אינטגרציות ← Webhooks ← לחץ על השורה של ה-webhook שלך).
2. בסעיף מפתח חתימה (Signing secret), לחץ על הפקה (Generate).
3. העתק את המפתח (הוא מתחיל ב-whsec_) ושמור אותו במערכת הקולטת שלך. התייחס אליו כמו אל סיסמה.

אתה יכול לחזור ולחשוף, להעתיק, להחליף או לכבות את המפתח בכל עת מאותו לוח בקרה.

מה אנחנו שולחים #

ברגע שהחתימה מופעלת, כל משלוח עבור ה-webhook הזה נושא את שני כותרי ה-HTTP הנוספים הבאים:

שלושת אלו נמצאים בכל משלוח, חתום או לא:

כיצד לאמת #

החתימה היא HMAC-SHA256 של המחרוזת <timestamp>.<raw request body>, תוך שימוש בסוד החתימה שלך כמפתח.

אמת מול גוף הבקשה הגולמי (raw request body) — הבייטים המדויקים שקיבלת. אם המערכת שלך מנתחת את ה-JSON ומסדרת אותו מחדש לפני הבדיקה, הבייטים עלולים להשתנות והחתימה לא תתאים.

דוגמה ב-Node.js:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"]; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature.replace("v1=", "")), Buffer.from(expected));
}

דוגמה ב-Python:

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"].replace("v1=", "")

    # Reject anything older than 5 minutes so a captured request can't be replayed later.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()

    return hmac.compare_digest(signature, expected)

השוו חתימות באמצעות פונקציה בטוחה מפני תזמון (timing-safe) (timingSafeEqual / compare_digest), ולא באמצעות ==. זה לא עולה דבר ומונע סוג עדין של התקפה.

החלפת הסוד #

לחצו על Rotate (רענון) כדי להחליף את הסוד. ההחלפה היא מיידית: המשלוח הבא בלבד ייחתם באמצעות הסוד החדש. אם נקודת הקצה שלכם פעילה, קבלו את שני הסודות (הישן והחדש) למשך מספר דקות בזמן שאתם פורסים את החדש.

כיבוי החתימה פשוט מפסיק את שליחת כותרות החתימה.

ניסיון חוזר למשלוחים שנכשלו #

כברירת מחדל, משלוח שנכשל לא מבוצע שוב — אם המערכת שלך מושבתת באותו רגע, האירוע הזה יוחמץ.

הפעילו את Retry failed deliveries (נסה שוב משלוחים שנכשלו) ב-webhook (בטופס היצירה/עריכה) ואנחנו נמשיך לנסות:

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

מה מבוצע שוב: בעיות זמניות — השרת שלך מחזיר שגיאת 5xx, פסק זמן (timeout), או כשל בחיבור.

מה לא מופעל מחדש: אם נקודת הקצה שלכם דוחה את הבקשה עצמה (כל שגיאת 4xx), אנחנו לא ננסה שוב — שליחה חוזרת של אותה בקשה בדיוק רק תניב את אותה דחייה.

אילו אירועים מבוצעים שוב (retry): כל אירוע, החל מ-24 בספטמבר 2026. זה כולל את ה-webhooks של התגיות (contact_tags_updated), שלושת אירועי המשימות, הסיכום היומי, ה-webhook של הסיכום, הודעה חדשה, צ’אט הסתיים, איש קשר הושהה, איש קשר חודש, איש קשר במצב ‘נא לא להפריע’, איש קשר הוצא מארכיון, יתרה נמוכה, אירועי שידור, ואירועי איש קשר ופעילות: איש קשר נוצר, פגישה נקבעה, התראה אנושית, תשובות, קריאות, משלוחים, קרדיטים שנוצלו וקרדיטים שנטענו. לפני תאריך זה, הודעה חדשה, צ’אט הסתיים, איש קשר הושהה, איש קשר חודש, איש קשר במצב ‘נא לא להפריע’, איש קשר הוצא מארכיון וה-webhook של הסיכום נשלחו פעם אחת ללא קשר למתג. כל אירוע נושא X-Webhook-Delivery, כך שכלל מניעת כפילויות אחד מכסה את כולם.

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

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

אמינות Webhook #

• Your AI Connector שולחת Webhooks דרך חיבור מאובטח (HTTPS). ודא שכתובת האינטרנט שאתה מספק משתמשת ב-HTTPS.
• אם המערכת שלך מחזירה שגיאה, המשלוח נחשב כנכשל.
• עקוב אחר זמן הפעילות (uptime) של המערכת המקבלת כדי להימנע מאיבוד אירועים.
• עבור תהליכי עבודה קריטיים, הפעל את ניסיון חוזר של משלוחים שנכשלו, ושקול גם מנגנון גיבוי.

Webhooks כבים אוטומטית לאחר כשלים חוזרים ונשנים. אם כתובת ה-URL של ה-webhook שלך נכשלת שוב ושוב (כ-5 שגיאות ברצף, או 3 ברצף עבור שגיאות מסוג הגדרה), Your AI Connector מפסיקה אוטומטית לשלוח אירועים לכתובת URL זו. כדי להחזיר אותו לפעולה ברגע שנקודת הקצה שלך תקינה: ערוך את ה-webhook ושמור אותו עם כתובת URL שונה (כל שינוי ב-URL מפעיל אותו מחדש), או השתמש ב-נקודת קצה להפעלה מחדש דרך ה-API — שמירה מחדש עם אותה כתובת URL אינה מספיקה. התמיכה יכולה גם להפעיל אותו מחדש עבורך.

פתרון בעיות #

צעדים הבאים #

• אינטגרציה עם GoHighLevel — השתמש ב-Webhooks כדי לשלב את Your AI Connector עם GHL.
• גישת API — שלב Webhooks עם ה-API לאוטומציות עוצמתיות.
• שימוש בתגיות לתיוג אנשי קשר — הגדר תגיות שמפעילות את ה-Webhooks שלך.