Webhooks לאירועים של סוכנים

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

Webhook הוא כתובת אצלכם ש-Fine Structure פונה אליה כשמשהו קורה. עם webhooks לסוכנים, ה-CRM או כלי אוטומציה כמו Make יכולים לתעד כל שיחה של הסוכנים עם לקוחות, או להתריע לצוות כשסוכן סיים תשובה. המסך נמצא ב-/agent-webhooks.

יוצרים webhook

1. לוחצים על + webhook חדש: מקלידים בכתובת היעד (URL) את הכתובת שתקבל את האירועים, למשל כתובת ה-webhook של תרחיש ב-Make. היא חייבת להתחיל ב-http://‎ או https://‎. את שדה מזהה הסוכן משאירים ריק כדי לכסות את כל הסוכנים, או מדביקים מזהה של סוכן אחד.

2. בוחרים אירועים: מסמנים את האירועים שרוצים. אם לא מסמנים כלום, נשלחים כל האירועים. מוסיפים תיאור קצר כמו "סנכרון ל-CRM" ולוחצים צור.

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

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

בלי קוד: כל תשובה של סוכן נשלחת ל-Make או ל-Zapier

דוגמה: סטודיו פילאטיס רוצה שכל שיחה של סוכן הוואטסאפ תיכתב כשורה בגיליון Google. את הכתיבה עושים Make או Zapier; Fine Structure רק צריכה להודיע להם שמשהו קרה.

1. מקבלים כתובת מכלי האוטומציה: ב-Make פותחים תרחיש עם מודול Webhooks והטריגר custom webhook; ב-Zapier פותחים Zap עם Webhooks by Zapier והטריגר catch hook. הכלי מציג כתובת שמתחילה ב-https://‎. מעתיקים אותה.

2. מדביקים אותה ב-Fine Structure: פותחים את /agent-webhooks, לוחצים + webhook חדש ומדביקים את הכתובת בכתובת היעד (URL). מסמנים message.completed כדי לקבל כל תשובה שהסתיימה. לוחצים צור ומעתיקים את הסוד שמופיע פעם אחת.

3. בוחרים סוכן (לא חובה): משאירים את מזהה סוכן ריק כדי לכסות את כל הסוכנים. לסוכן אחד בלבד, פותחים אותו בהסוכנים שלי: שורת הכתובת מסתיימת אז ב-agent= ובמזהה שלו, שמתחיל ב-agt_. מדביקים את המזהה.

4. שולחים בדיקה: לוחצים בדיקה בשורה של ה-webhook. ב-Make או ב-Zapier אמור להופיע אירוע בדיקה; משתמשים בו כדי למפות שדות כמו data.content (הטקסט) ו-data.channel לגיליון. לוג מציג כל שליחה והאם היא קיבלה תשובת 2xx.

המילים במסך הזה

מילה | מה היא אומרת

Webhook | כתובת אצלכם ש-Fine Structure פונה אליה לבד כשמשהו קורה, כמו פעמון דלת למערכת שלכם.

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

2xx | משפחת התשובות "בסדר, התקבל" שכתובת אינטרנט מחזירה (200, 201...). כל תשובה אחרת נחשבת כישלון ונשלחת שוב.

HMAC והסוד | חותמת מתמטית שנוצרת מההודעה ומהסוד שלכם. רק מי שמחזיק בסוד יכול ליצור את אותה חותמת, ולכן חותמת תואמת מוכיחה שהקריאה הגיעה מ-Fine Structure.

X-FSE2-Signature | הכותרת שבה החותמת מגיעה. Make ו-Zapier מקבלים את הקריאה בלי לבדוק אותה; שרת של מפתח צריך לבדוק אותה.

אירוע | נשלח כש...

conversation.created | נפתחת שיחה חדשה עם סוכן, בכל ערוץ.

message.created | נכתבת הודעה, מהלקוח או מהסוכן.

message.completed | הסוכן סיים לענות.

ping | לחצתם על כפתור הבדיקה.

מה מגיע

כל קריאה היא HTTP POST עם גוף JSON. הכותרת X-FSE2-Signature מכילה HMAC-SHA256 של הגוף הגולמי שנוצר עם הסוד שלכם, ומתחילה ב-sha256=. בודקים אותה לפני שסומכים על הקריאה. אירועי הודעה כוללים את טקסט ההודעה, אלא אם זה כובה בצד השרת.

{
  "event": "message.completed",
  "event_id": "<message id>:message.completed",
  "created_at": "2026-11-14T09:12:04",
  "agent_id": "...",
  "conversation_id": "...",
  "data": {
    "message_id": "...",
    "role": "assistant",
    "status": "completed",
    "channel": "whatsapp",
    "app_id": "...",
    "content": "היי דנה, השיעור שלך נקבע ליום שלישי ב-18:00."
  }
}

עונים בכל סטטוס 2xx. קריאה שנכשלה נשלחת שוב עד 6 פעמים, עם המתנה שהולכת וגדלה (30 שניות, 2 דקות, 10 דקות, 30 דקות, שעתיים), ואז נעצרת. קריאות יכולות להגיע לא לפי הסדר, ולכן משתמשים ב-event_id כדי לסנן כפילויות. דוגמאות קוד לבדיקת החתימה נמצאות במדריך ה-webhooks.

השהיה, סוד חדש, מחיקה

בכל שורה: השהה משהה את ה-webhook (והפעל מחזיר אותו), secret חדש יוצר סוד חתימה חדש ומציג אותו פעם אחת (הישן מפסיק לעבוד), ומחק מוחק את ה-webhook אחרי אישור.

Questions

Q: ה-webhook יראה שיחות של סוכנים שלא בחרתי?

A: רק אם השארתם את מזהה הסוכן ריק, שפירושו כל הסוכנים.

Q: בלוג כתוב dead.

A: כל 6 הנסיונות נכשלו. בודקים שהכתובת עונה בסטטוס 2xx ושולחים ping לבדיקה.

Q: זה אותו דבר כמו ה-webhook של החוזים?

A: לא. לחוזים יש webhook משלהם לחוזים חתומים, ראו כלים מתקדמים לחוזים.

Q: אפשר לקבל הודעות בלי שרת?

A: כן. מדביקים את כתובת ה-webhook של כלי אוטומציה כמו Make או Zapier וממשיכים משם.

Q: הבדיקה לא מופיעה ב-Make או ב-Zapier.

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

Q: בלוג כתוב 404 או 410.

A: הכתובת כבר לא קיימת, למשל התרחיש נמחק. מעתיקים כתובת חדשה מהכלי ויוצרים את ה-webhook מחדש.

Related: What an AI agent is, API keys for your account, Advanced contract tools, Send files into a notebook automatically (notebook webhooks), Connect your services (Connections)