שולחים כל שיחה והודעה חדשה של סוכן לשרת או לכלי האוטומציה שלכם, עם חתימה שמאפשרת לבדוק שזה הגיע מ-Fine Structure.
Webhook הוא כתובת אצלכם ש-Fine Structure פונה אליה כשמשהו קורה. עם webhooks לסוכנים, ה-CRM או כלי אוטומציה כמו Make יכולים לתעד כל שיחה של הסוכנים עם לקוחות, או להתריע לצוות כשסוכן סיים תשובה. המסך נמצא ב-/agent-webhooks.
1. לוחצים על + webhook חדש: מקלידים בכתובת היעד (URL) את הכתובת שתקבל את האירועים, למשל כתובת ה-webhook של תרחיש ב-Make. היא חייבת להתחיל ב-http:// או https://. את שדה מזהה הסוכן משאירים ריק כדי לכסות את כל הסוכנים, או מדביקים מזהה של סוכן אחד.
2. בוחרים אירועים: מסמנים את האירועים שרוצים. אם לא מסמנים כלום, נשלחים כל האירועים. מוסיפים תיאור קצר כמו "סנכרון ל-CRM" ולוחצים צור.
3. מעתיקים את הסוד: תיבה מציגה את סוד החתימה פעם אחת. מעתיקים אותו לשרת; בעזרתו בודקים כל קריאה. בסיום לוחצים הבנתי.
4. בודקים: בשורה של ה-webhook לוחצים בדיקה כדי לשלוח אירוע ping, ואז לוג כדי לראות כל שליחה עם הסטטוס, תשובת ה-HTTP ומספר הנסיונות.
דוגמה: סטודיו פילאטיס רוצה שכל שיחה של סוכן הוואטסאפ תיכתב כשורה בגיליון 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 אחרי אישור.
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)