Webhooks #

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

מהם Webhooks? #

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

Webhooks שולחים נתונים רק מחוץ ל-Your AI Connector. Webhook הוא כביש חד-סטרי מ-Your AI Connector אל הכלים האחרים שלך. אין כתובת URL של webhook ששולחת לידים, אנשי קשר או הודעות לתוך הפלטפורמה. כדי להזין ליד חדש — מטופס באתר, מה-CRM שלך או מ-GoHighLevel — המערכת שלך מבצעת קריאת API במקום זאת. עיין ב-גישת API (פעולת יצירת איש קשר) וב-משפכים. הדבר היחיד שאתה צריך עבור הכיוון הנכנס הוא מפתח ה-API שלך, שנמצא בסעיף משלו — עיין ב-גישת API. דף ה-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 זה יקבל — כל 22 האירועים מפורטים ב-22 אירועי ה-Webhook.
6. (אופציונלי) הפעל את נסה שוב משלוחים שנכשלו (Retry failed deliveries) אם ברצונך ש-Your AI Connector ימשיך לנסות במקרה של כשל זמני — ראה ניסיון חוזר של משלוחים שנכשלו.
7. לחץ על צור webhook (Create 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.

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

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

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

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

subscribed_to_tags אינו מגביל אירועי webhook לתגית מסוימת. הוא רק מצמצם אילו תגיות מייצרות התראה על סיכום שיחה. כדי לקבל בקשה כאשר מוחלת תגית ספציפית, הגדר כתובת 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" }
}

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

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

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

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

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

22 אירועי ה-Webhook #

22 אירועי ה-webhook, עם תווית התצוגה שאתה מסמן באפליקציה וקוד ה-event שנשלח במטען (payload). קוד ה-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
  },
  "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"
  }
}

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

Webhook הודעה חדשה #

ה-Webhook הזה מופעל בכל פעם שהודעה מתווספת לשיחה, בכל ערוץ. הוא מכסה את שני הכיוונים: הודעות שאיש הקשר שולח אליך, והודעות שה-AI, הצוות שלך או קמפיין שולחים לו. זהו ה-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
  },
  "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"
  }
}

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

רשומות 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
  },
  "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,
    "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 מחובר, לכן אל תמתין לו לנצח.

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

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

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

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

שם האירוע #

contact_tags_updated

מתי זה מופעל #

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

אם לאיש הקשר יש גם סוכן וגם קמפיין, והתגיות של הקמפיין נושאות כתובות 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"
    }
  },
  "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 כמו כל אירוע אחר — ראה אירועי הפעלה זמינים ו-22 אירועי ה-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): webhooks של תגיות (contact_tags_updated), שלושת אירועי המשימות, והסיכום היומי. השאר נשלחים פעם אחת, כך שעבורם למתג אין משמעות. כל אירוע עדיין נושא את 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 שלך.