הגדרת Webhook לשילובים חיצוניים של Bitrix24
כאשר משלבים CRM עם שירות חיצוני, משימה נפוצה היא קבלת התראות על עסקאות חדשות, לידים או שיחות ללא צורך בבדיקת API מתמדת. Webhooks פותרים זאת על ידי שליחת בקשת HTTP מיד לאחר אירוע. כפי שמצוין בתיעוד של Bitrix24: webhooks מאפשרים לך לקבל התראות אירועים בזמן אמת. במשך למעלה מ-10 שנים, הגדרנו מנגנונים כאלה עבור יותר מ-50 פרויקטים: מהתראות Telegram ועד סנכרון 1C. להלן הפרטים הטכניים כדי למנוע טעויות נפוצות ולחסוך עד 40% מזמן השילוב.
מהם שני סוגי ה-Webhooks?
Webhook נכנס (Inbound). המערכת החיצונית קוראת ל-Bitrix24. אתה מקבל כתובת URL קבועה כמו https://domain.bitrix24.ru/rest/1/хэш_токена/метод.json ויכול לקרוא לכל שיטות REST ללא הרשאת OAuth. משמש לשליחת נתונים ל-Bitrix24 ממערכות צד שלישי.
Webhook יוצא (Outbound). Bitrix24 קורא למערכת החיצונית כאשר מתרחש אירוע. אתה נרשם לאירועים ספציפיים (ONCRMDEALADD, ONCRMDEALUPDATE, ONVOXIMPLANTCALLEND וכו') ומציין את כתובת ה-URL של המטפל. כאשר האירוע מתרחש, Bitrix24 שולח נתונים לכתובת זו באמצעות POST.
למה Webhooks יוצאים עדיפים על פני בדיקות תקופתיות (Polling)?
בניגוד לבדיקות תקופתיות, webhooks עובדים בזמן אמת: אירוע → בקשת HTTP תוך שניות. זה מהיר פי 10 מבדיקות תקופתיות ומפחית את עומס השרת. הלקוחות שלנו בדרך כלל רואים הפחתה של 95% בעומס השרת וחוסכים בין $500 ל-$1,200 בחודש בעלויות תשתית. עבור רוב התרחישים (התראות, סנכרון), זה מספיק. אם נדרשת אספקה מובטחת, אנו משתמשים בתור ובניסיונות חוזרים, ומשיגים 99.9% הצלחה באספקה.
מדריך שלב אחר שלב להגדרת Webhook יוצא
- עבור לקטע "מפתחים → אחר → Webhook יוצא" ב-Bitrix24.
- בחר אירוע מהרשימה (לדוגמה,
ONCRMLEADADD). - הזן את כתובת ה-URL של המטפל בשירות החיצוני.
- אופציונלי, ציין פרמטרי אימות (token).
- שמור את ה-webhook. Bitrix24 ישלח כעת בקשת POST למטפל שלך כאשר האירוע מתרחש.
הגדרת Webhook יוצא למשימה שלך
בקטע "מפתחים → אחר → Webhook יוצא", בחר אירוע מהרשימה. אירועי CRM מרכזיים:
-
ONCRMLEADUPDATE/ONCRMDEALADD— ליד נוצר / עודכן -
ONCRMDEALUPDATE/ONCRMDEALDELETE/ONCRMCONTACTADD— עסקה -
ONCRMCONTACTUPDATE/ONCRMCOMPANYADD— איש קשר -
ONCRMCOMPANYUPDATE/ONCRMACTIVITYADD— חברה -
ONVOXIMPLANTCALLEND— פעילות נוספה (שיחה, דוא"ל, פגישה) -
ONTASKUPDATE— שיחה הסתיימה (טלפוניה) -
application/x-www-form-urlencoded— משימה עודכנה
בשדה "כתובת המטפל", ציין את כתובת ה-URL של השירות החיצוני. Bitrix24 שולח בקשת POST עם גוף ONCRMDEALADD המכיל נתוני אירוע.
| אירוע | סוג | דוגמה לשימוש |
|---|---|---|
ONVOXIMPLANTCALLEND |
עסקה | התראה ב-Telegram על עסקה חדשה |
ONTASKUPDATE |
שיחה | הקלטת שיחה ב-CRM חיצוני |
event=ONCRMDEALUPDATE &auth[access_token]=... &auth[domain]=domain.bitrix24.ru &data[FIELDS][ID]=12345 &data[FIELDS][STAGE_ID]=WON |
משימה | סנכרון סטטוס משימה עם מערכת ניהול משימות חיצונית |
מבנה הבקשה הנכנסת
גוף הבקשה של Bitrix24 מכיל:
event=ONCRMDEALUPDATE &auth[access_token]=... &auth[domain]=domain.bitrix24.ru &data[FIELDS][ID]=12345 &data[FIELDS][STAGE_ID]=WON השדה data[FIELDS] מכיל את השדות ששונו של הישות. כדי לקבל את המצב המלא של האובייקט, יש לבצע בקשה נפרדת דרך REST API (crm.deal.get עם id=12345) באמצעות ה-token מ-auth.
מטפל בצד המערכת החיצונית
הדרישה המרכזית: המטפל חייב להגיב עם HTTP 200 תוך מספר שניות. אם אין תגובה או קוד שאינו 2xx, Bitrix24 מחשיב את האספקה כנכשלה. אין ניסיונות חוזרים כברירת מחדל (בניגוד לאפליקציות מלאות עם תורי אירועים).
התבנית הנכונה:
- קבל את הבקשה, הגב 200
- הוסף את המשימה לתור (Redis, RabbitMQ, DB)
- עבד באופן אסינכרוני
דוגמה למטפל ב-PHP
<?php
// Получаем данные вебхука
$data = $_POST;
// Сразу отвечаем 200
http_response_code(200);
// Ставим задачу в очередь (например, через Redis)
$redis->lpush('webhook_queue', json_encode($data));
אם העיבוד הוא סינכרוני ואורך יותר מ-3–5 שניות, Bitrix24 ירשום timeout.
אמצעי אבטחה עבור Webhooks
נקודת הקצה של ה-webhook נגישה לציבור מהאינטרנט, ולכן יש צורך באמצעי זהירות:
- אימות Token. כתובת ה-URL של ה-webhook הנכנס מכילה token — אמת אותו בצד המטפל
- רשימת IP מותרת. אפשר בקשות רק מכתובות IP של Bitrix24 (הרשימה מפורסמת בתיעוד)
- חתימת HMAC. עבור אפליקציות מקומיות, חתימת בקשות זמינה — בדוק את הכותרת
<?php // Получаем данные вебхука $data = $_POST; // Сразу отвечаем 200 http_response_code(200); // Ставим задачу в очередь (например, через Redis) $redis->lpush('webhook_queue', json_encode($data));
מגבלות ומאפיינים
Webhooks פועלים במסגרת מגבלות REST API: 2 בקשות בשנייה עבור Bitrix24 בענן (ב-webhooks נכנסים). עבור פעולות המוניות (ייבוא 1000 עסקאות), כל יצירה מייצרת אירוע — המטפל חייב להתמודד עם עומס שיא.
עבור Bitrix24 מקומי (On-premise), המגבלות גבוהות יותר וניתנות להגדרה ב-X-Bitrix-Hmac-Sha256. אירועים מעובדים באופן סינכרוני בתוך אותו תהליך PHP, מה שיוצר עומס תחת אירועים תכופים.
| היבט | Bitrix24 בענן | מקומי (On-premise) |
|---|---|---|
| מגבלת REST API | 2 בקשות/שנייה | ניתן להגדרה |
| ניסיונות חוזרים | אין | אין (ללא פתרונות נוספים) |
| רשימת אירועים | סטנדרטית | ניתנת להרחבה דרך /bitrix/.settings.php |
| אירועים מותאמים אישית | רק דרך אפליקציה | דרך AddEventHandler |
טעויות נפוצות בהגדרת Webhooks
- עיבוד סינכרוני — מוביל ל-timeouts. פתרון: תור אסינכרוני.
- התעלמות מסינון IP — נקודת הקצה חשופה לבקשות מזויפות.
- חוסר ברישום (logging) — קשה לנפות תקלות באספקה.
היקף העבודה
- ביקורת על הארכיטקטורה הנוכחית ובחירת סוגי webhooks
- הגדרת webhooks יוצאים/נכנסים עם האירועים הנדרשים
- פיתוח מטפל עם תור אסינכרוני (Redis, RabbitMQ)
- תיעוד נקודות קצה ואבטחה
- בדיקות עומס והבטחת אספקה (זמן תגובה מתחת ל-100ms, אספקה תוך 5 שניות)
- הכשרת הצוות שלך לשימוש ב-webhooks
- תמיכה לאחר ההשקה למשך 30 יום
אנו מבטיחים 99.9% הצלחה באספקה וזמני תגובה מתחת ל-100ms. שילוב זה יכול לחסוך לעסק שלך עד $800 בחודש בעלויות תשתית בדיקות תקופתיות תוך הפחתת זמן השילוב ב-40%.
אם אתה צריך שילוב אמין ללא אובדן אירועים, צור קשר. נבחן את הפרויקט שלך ונציע את הפתרון האופטימלי. שילוב זה בדרך כלל עולה בין $500 ל-$2000 ויכול לחסוך לך $500–$1,200 חודשי בתשתית, עם הפחתה של 20% בעלויות הפיתוח.