הגדרת 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 וכו') ומציין את כתובת ה-handler. כאשר האירוע מתרחש, Bitrix24 שולח נתונים לכתובת זו באמצעות POST.
למה Webhooks יוצאים עדיפים על פני בדיקות תקופתיות (Polling)?
בניגוד לבדיקות תקופתיות, webhooks עובדים בזמן אמת: אירוע → בקשת HTTP תוך שניות. זה מהיר פי 10 מבדיקות תקופתיות ומפחית את עומס השרת. הלקוחות שלנו בדרך כלל רואים הפחתה של 95% בעומס השרת וחוסכים בין $500 ל-$1,200 בחודש בעלויות תשתית. עבור רוב התרחישים (התראות, סנכרון), זה מספיק. אם נדרשת אספקה מובטחת, אנו משתמשים בתור וניסיונות חוזרים, ומשיגים 99.9% הצלחה באספקה.
מדריך שלב-אחר-שלב להגדרת Webhook יוצא
- עבור לקטע "מפתחים → אחר → Webhook יוצא" ב-Bitrix24.
- בחר אירוע מהרשימה (לדוגמה,
ONCRMLEADADD). - הזן את כתובת ה-handler של השירות החיצוני.
- אופציונלי: ציין פרמטרי אימות (token).
- שמור את ה-webhook. Bitrix24 ישלח כעת בקשת POST ל-handler שלך כאשר האירוע מתרחש.
הגדרת Webhook יוצא למשימה שלך
בקטע "מפתחים → אחר → Webhook יוצא", בחר אירוע מהרשימה. אירועי CRM מרכזיים:
-
ONCRMLEADUPDATE/ONCRMDEALADD— ליד נוצר / עודכן -
ONCRMDEALUPDATE/ONCRMDEALDELETE/ONCRMCONTACTADD— עסקה -
ONCRMCONTACTUPDATE/ONCRMCOMPANYADD— איש קשר -
ONCRMCOMPANYUPDATE/ONCRMACTIVITYADD— חברה -
ONVOXIMPLANTCALLEND— פעילות נוספה (שיחה, אימייל, פגישה) -
ONTASKUPDATE— שיחה הסתיימה (טלפוניה) -
application/x-www-form-urlencoded— משימה עודכנה
בשדה "כתובת Handler", ציין את כתובת ה-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.
Handler בצד המערכת החיצונית
הדרישה המרכזית: ה-handler חייב להשיב עם HTTP 200 תוך מספר שניות. אם אין תשובה או קוד שאינו 2xx, Bitrix24 מחשיב את האספקה כנכשלה. אין ניסיונות חוזרים כברירת מחדל (בניגוד לאפליקציות מלאות עם תורי אירועים).
התבנית הנכונה:
- קבל את הבקשה, השב עם 200
- הוסף את המשימה לתור (Redis, RabbitMQ, DB)
- עבד באופן אסינכרוני
דוגמה ל-handler ב-PHP
<?php // Получаем данные вебхука $data = $_POST; // Сразу отвечаем 200 http_response_code(200); // Ставим задачу в очередь (например, через Redis) $redis->lpush('webhook_queue', json_encode($data)); אם העיבוד הוא סינכרוני ואורך יותר מ-3–5 שניות, Bitrix24 ירשום timeout.
אמצעי אבטחה עבור Webhooks
נקודת הקצה של ה-webhook נגישה לציבור מהאינטרנט, ולכן יש צורך באמצעי זהירות:
- אימות Token. כתובת ה-webhook הנכנס מכילה token — אמת אותו בצד ה-handler
- רשימת 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 עסקאות), כל יצירה מייצרת אירוע — ה-handler חייב להתמודד עם עומס שיא.
עבור Bitrix24 מקומי (On-premise), המגבלות גבוהות יותר וניתנות להגדרה ב-X-Bitrix-Hmac-Sha256. אירועים מעובדים באופן סינכרוני באותו תהליך PHP, מה שיוצר עומס תחת אירועים תכופים.
| היבט | Bitrix24 בענן | On-premise |
|---|---|---|
| מגבלת REST API | 2 בקשות/שנייה | ניתן להגדרה |
| ניסיונות חוזרים | אין | אין (ללא פתרונות נוספים) |
| רשימת אירועים | סטנדרטית | ניתנת להרחבה באמצעות /bitrix/.settings.php |
| אירועים מותאמים אישית | רק דרך אפליקציה | באמצעות AddEventHandler |
טעויות נפוצות בהגדרת Webhooks
- עיבוד סינכרוני — מוביל ל-timeouts. פתרון: תור אסינכרוני.
- התעלמות מסינון IP — נקודת הקצה חשופה לבקשות מזויפות.
- חוסר ברישום (Logging) — קשה לנפות תקלות באספקה.
היקף העבודה
- ביקורת על הארכיטקטורה הנוכחית ובחירת סוגי webhooks
- הגדרת webhooks יוצאים/נכנסים עם האירועים הנדרשים
- פיתוח handler עם תור אסינכרוני (Redis, RabbitMQ)
- תיעוד נקודות קצה ואבטחה
- בדיקות עומס והבטחת אספקה (זמן תגובה מתחת ל-100ms, אספקה תוך 5 שניות)
- הכשרת הצוות שלך לשימוש ב-webhooks
- תמיכה לאחר ההשקה למשך 30 יום
אנו מבטיחים 99.9% הצלחה באספקה וזמני תגובה מתחת ל-100ms. אינטגרציה זו יכולה לחסוך לעסק שלך עד $800 בחודש בעלויות תשתית בדיקות תקופתיות, תוך הפחתת זמן האינטגרציה ב-40%.
אם אתה זקוק לאינטגרציה אמינה ללא אובדן אירועים, צור איתנו קשר. אנו נבחן את הפרויקט שלך בחינם ונציע את הפתרון האופטימלי. אינטגרציה זו בדרך כלל עולה בין $500 ל-$2000 ויכולה לחסוך לך $500–$1,200 חודשי בתשתית, עם הפחתה של 20% בעלויות הפיתוח.