הרשמה ל-Webhook דרך ה-API: הוספה, רשימה ומחיקה

המערכת שלכם נרשמת להודעות בעצמה

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

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

שימו לב: ההרשמות הן של תוסף שליחת אירועים (Webhook), ולכן צריך שגם הוא וגם תוסף ממשק API יהיו פעילים. את ההודעות עצמן שולח תוסף ה-Webhook, ולא ה-API.

מה צריך

• שני התוספים פעילים: ממשק API ושליחת אירועים (Webhook).
• מפתח "קריאה וכתיבה": מפתח "קריאה בלבד" יכול רק להציג את ההרשמות.
• כתובת שמתחילה ב-https: הכתובת בצד שלכם שתקבל את ההודעות.

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

הוספת הרשמה: webhook_add

שולחים את סוג האירוע ב-event, בשם שלו, למשל lead_converted, או במספר שלו, ואת הכתובת שלכם ב-target_url:

{
  "api_token": "<המפתח שלכם>",
  "event": "lead_converted",
  "target_url": "https://example.com/bigboss/webhook"
}

ההודעה היא "ההרשמה נוספה", ובתשובה חוזרת ההרשמה עצמה:

"data": {
  "subscription_id": 312,
  "event": "lead_converted",
  "event_type_id": 5,
  "target_url": "https://example.com/bigboss/webhook",
  "is_active": 1,
  "signed": 1,
  "auto_disabled_at": null,
  "signing_secret": "whsec_..."
}

• subscription_id: מספר ההרשמה. שומרים אותו, כי לפיו מוחקים אותה.
• event_type_id: מספר סוג האירוע.
• is_active: 1 כשההרשמה פעילה.
• signed: 1 כשההודעות של ההרשמה חתומות. הרשמה שנוספת דרך ה-API חתומה מההתחלה.
• signing_secret: סוד החתימה. עליו בסעיף הבא.

כשמשהו לא תקין:

• אותו אירוע לאותה כתובת פעם שנייה: 409 "אירוע זה כבר קיים במערכת", ולא נוצרת הרשמה כפולה.
• כתובת שאינה https, למשל http: 400 "כתובת נקודת הקצה אינה תקינה – יש להזין כתובת מלאה ומאובטחת".
• אירוע שלא קיים: 400 "שדה event לא תקין – שם האירוע (למשל document_added) או מספרו".
• מפתח "קריאה בלבד": 403 "מפתח זה מוגדר לקריאה בלבד".

סוד החתימה: פעם אחת

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

בעזרת הסוד בודקים שהודעה הגיעה מביג בוס. כל הודעה של הרשמה חתומה מגיעה עם הכותרת X-BigBoss-Signature, בצורה t=…,v1=…. הערך של v1 הוא HMAC-SHA256 בסוד של ההרשמה, על הערך של t, נקודה, וגוף ההודעה כמו שהתקבל. המערכת שלכם מחשבת את אותו ערך ומשווה.

במסך "ניהול Webhook" הרשמה כזו מופיעה כמו כל הרשמה אחרת, ובעמודה "חתימה" רשום "יש".

נסו את מערכת ביג בוס לניהול העסק ל-45 יום בחינם >>

רשימת ההרשמות: webhook_list

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

{
  "api_token": "<המפתח שלכם>"
}

ב-signed רואים איזו הרשמה חתומה (1) ואיזו לא (0), וב-is_active איזו פעילה. כשאין הרשמות בכלל חוזר 204 "לא נמצאו הרשמות".

מחיקת הרשמה: webhook_delete

שולחים את מספר ההרשמה ב-subscription_id:

{
  "api_token": "<המפתח שלכם>",
  "subscription_id": 312
}

ההודעה היא "ההרשמה נמחקה". מחיקה חוזרת של אותה הרשמה מחזירה 404 "ההרשמה לא נמצאה", ולכן אפשר לשלוח אותה שוב בלי חשש כשלא ברור אם הבקשה הראשונה עברה.

מפתח לקריאה בלבד

מפתח "קריאה בלבד" יכול להציג את ההרשמות ב-webhook_list, אבל הוספה נדחית בו ב-403 "מפתח זה מוגדר לקריאה בלבד". מערכת שמנהלת את ההרשמות שלה צריכה מפתח "קריאה וכתיבה". מערכת שרק בודקת אילו הרשמות קיימות יכולה להסתפק במפתח "קריאה בלבד".

איך ביג בוס עוזרת לנהל הרשמות ל-Webhook מתוך המערכת שלכם, ומה היא לא עושה

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

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

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

נסו את מערכת ביג בוס לניהול העסק ל-45 יום בחינם >>

יש שאלה לפני שמתחילים? דברו איתנו

מדריכים נוספים

• מה עושה ממשק ה-API של ביג בוס, ומה לא: ממשק API מול Webhook, ומה כל אחד עושה.
• הקריאה הראשונה ל-API: מבנה הבקשה, התשובה וקודי התשובה: מבנה הבקשה והתשובה, וקודי התשובה.
• יומן קריאות Api: מה המערכת שלכם שלחה, ומה ביג בוס ענתה: גם בקשות להוספת הרשמה נרשמות ביומן, כולל אלה שנדחו.
• ממשק API בביג בוס: כל המדריכים של התוסף.

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