קליטת ההודעה בצד שלכם: כתובת, מפתח ותשובה

מה המערכת המקבלת צריכה לעשות

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

בהמשך: איך נראית הבקשה שמגיעה, ארבעה כללים לכתובת, מה קורה כשהיא לא עונה, ואיך בודקים שההודעות מגיעות.

הבקשה שמגיעה

כל הודעה היא בקשת POST לכתובת שהוזנה בשדה "כתובת נקודת הקצה", עם שתי כותרות: Content-Type: application/json, ו-Authorization שבה המילה Bearer ואחריה הסיסמה שהוקלדה בשדה "מפתח Api". הגוף הוא JSON מוזח עם פרטי הרשומה בלבד. כך נראית הודעה על ליד חדש (הערכים לדוגמה):

POST https://example.com/bigboss-webhook?type=lead-added
Content-Type: application/json
Authorization: Bearer xxxxxxxx
{
  "lead_id": 1234,
  "company_name": "ליד לדוגמה",
  "contact_name": "איש קשר לדוגמה",
  "address": "",
  "city": "",
  "zip": "",
  "tel": "",
  "cel": "",
  "email": "[email protected]",
  "comments": ""
}

מזהים מגיעים כמספרים, סכומים עם נקודה עשרונית (למשל 59.0), ותאריכים בפורמט 2026-10-06T15:19:20, בשעון ישראל ובלי אזור זמן. השדות של כל סוג אירוע מפורטים במבנה ההודעה לכל סוג אירוע.

הסיסמה שבשדה "מפתח Api" נשלחת בכותרת Authorization, וההודעה נשלחת לכתובת שבשדה "כתובת נקודת הקצה".

ארבעה כללים לכתובת

1. https, ופתוחה לאינטרנט
הכתובת חייבת להתחיל ב-https. כתובת שמתחילה ב-http מציגה בטופס "שדה זה חייב להתחיל עם https", וכתובות של רשת פנימית נחסמות.

כתובת שמתחילה ב-http לא מתקבלת.

2. בודקים את הסיסמה
השדה נקרא "מפתח Api", אבל אין לו קשר לתוסף ממשק ה-API: זו סיסמה שאתם ממציאים, מזינים בביג בוס ושומרים גם במערכת המקבלת. היא שדה חובה, ובלעדיה מופיע "יש לעדכן ערך בשדה זה". בכל הודעה בודקים שהכותרת Authorization מכילה את הסיסמה הנכונה, ודוחים הודעה בלי סיסמה או עם סיסמה אחרת. זה האימות היחיד, כי אין חתימת HMAC ואין רשימת כתובות IP קבועה.

3. עונים מהר
ביג בוס מחכה לתשובה עד 15 שניות, ומחשיבה הצלחה רק קוד בטווח 2xx. תוכן התשובה לא נקרא, והפניה לכתובת אחרת (301 או 302) נחשבת כישלון. לכן עונים מיד שההודעה התקבלה, ורק אחר כך מטפלים בה.

4. יודעים איזה סוג אירוע הגיע
בגוף ההודעה אין שם אירוע, ואין מזהה או שעה של השליחה. הודעה על ליד חדש והודעה על ליד שעודכן נראות אותו דבר. הפתרון: כתובת נפרדת לכל סוג, או פרמטר שמוסיפים לכתובת, כמו ?type=lead-added בדוגמה. הפרמטר מגיע שלם בכל הודעה.

כשהמערכת שלכם לא עונה

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

ייתכן שאותה הודעה תגיע פעמיים. בבדיקה שלנו, גם הודעות שהכתובת ענתה עליהן בהצלחה נשלחו לפעמים שוב כעבור כדקה. לכן מזהים כפילויות לפי המזהה שבהודעה (lead_id, customer_id, document_id), ומעדכנים רשומה קיימת במקום ליצור חדשה. גם אין הבטחה שההודעות יגיעו לפי הסדר, כי ניסיון חוזר נשלח אחרי הודעות שיצאו בינתיים.

איך בודקים שההודעות מגיעות

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

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

כל שכבת המדריכים מרוכזת בעמוד שליחת אירועים למערכות חיצוניות (Webhook) בביג בוס.