התלונה הנפוצה ביותר על אינטגרציית webhook של Bitrix24: "זה עבד, ואז זה הפסיק." הסיבה היא כמעט תמיד זהה — ה-handler התחיל להגיב לאט יותר מ-5 שניות, Bitrix24 הפסיק לקרוא לו, ואף אחד לא שם לב כי לא היו לוגים. עם ניסיון של למעלה מ-10 שנים ו-50+ אינטגרציות מוצלחות, אנו מבטיחים אינטגרציית webhook עמידה לתקלות של Bitrix24. המהנדסים המוסמכים שלנו מבטיחים זמינות של 99.9% לנקודת הקצה של ה-webhook. אנו מתמודדים עם עומסי שיא כמו Black Friday ומעבדים עד 1000 אירועים בדקה. אם אתם צריכים אינטגרציה שלא תיכשל ברגע הקריטי ביותר, צרו קשר לייעוץ.
מהם Webhooks יוצאים ונכנסים?
Webhooks ב-Bitrix24 פועלים בשני כיוונים. Webhook יוצא — Bitrix24 קורא ל-URL שלכם כאשר מתרחש אירוע. ההרשמה מוגדרת בסעיף "מפתחים" או דרך event.bind ב-REST API. Bitrix24 שולח בקשת POST עם Content-Type: application/x-www-form-urlencoded. Webhook נכנס — המערכת שלכם קוראת ל-Bitrix24 דרך URL קבוע עם טוקן. נוח לאינטגרציות חד-כיווניות פשוטות ללא OAuth. לאינטגרציה דו-כיוונית, אנו משתמשים בדרך כלל בשני הסוגים: נכנס לשליחת נתונים ל-Bitrix24, ויוצא לקבלת אירועים.
הרשמה לאירועים דרך API
הרשמה פרוגרמטית אמינה יותר מהגדרה ידנית בממשק — היא לא תלויה בפעולות של מנהל המערכת וקל יותר להרחיב אותה. דוגמה להרשמה דרך Bitrix24 REST API:
הצגת קוד הרשמה
// Подписка через REST API (от имени OAuth-приложения) $b24->call('event.bind', [ 'event' => 'ONCRMDEALUPDATE', 'handler' => 'https://your-system.com/webhooks/bitrix24', 'auth_type' => 0, ]); לביטול הרשמה, השתמשו ב-// Подписка через REST API (от имени OAuth-приложения) $b24->call('event.bind', [ 'event' => 'ONCRMDEALUPDATE', 'handler' => 'https://your-system.com/webhooks/bitrix24', 'auth_type' => 0, ]); . קבלו את רשימת ההרשמות הפעילות דרך event.unbind.
עיבוד אירועים: תגובה מיידית ו-Idempotency
מבנה בקשת נכנסת
גוף בקשת ה-POST מ-Bitrix24 מכיל את האירוע, handler_id, טוקנים, והנתונים בפועל. חשוב: event.get מכיל רק את השדות שהשתנו, לא את האובייקט המלא. כדי לקבל את המצב הנוכחי של עסקה, יש צורך בקריאה נפרדת ל-data[FIELDS].
crm.deal.get הוא הטוקן לאימות מקור הבקשה. עבור Bitrix24 on-premise, אנו בודקים אותו מול טוקן האפליקציה.
תור אירועים: תבנית חיונית
דרישה מרכזית: ה-handler חייב להחזיר HTTP 200 תוך 5 שניות. כל דבר ארוך יותר הוא timeout. אנו משתמשים בתור אירועים (למשל, Laravel Queue). עיבוד מבוסס תור מהיר פי 10 מטיפול ישיר, ומפחית את זמן התגובה מ-5 שניות לפחות מ-100ms. הנה מימוש מינימלי:
הצגת קוד handler לתור
// routes/api.php (Laravel) Route::post('/webhooks/bitrix24', function (Request $request) { // Валидация токена — быстро if (!validateBitrixToken($request->input('auth.application_token'))) { return response('Forbidden', 403); } // Кладём в очередь — быстро ProcessBitrixEvent::dispatch($request->all()); // Немедленно отвечаем return response('OK', 200); }); // app/Jobs/ProcessBitrixEvent.php class ProcessBitrixEvent implements ShouldQueue { public $tries = 3; public $backoff = [60, 300, 900]; // 1 мин, 5 мин, 15 мин public function handle(): void { $event = $this->payload['event']; $dealId = $this->payload['data']['FIELDS']['ID']; // Теперь получаем полный объект $deal = $this->b24->call('crm.deal.get', ['id' => $dealId]); // ... обработка } } החשיבות של Idempotency
אותו אירוע עשוי להגיע פעמיים: Bitrix24 מנסה שוב במקרה של בעיות רשת, ופעולות אצווה מייצרות auth[application_token] עבור כל שדה. ה-handler חייב להיות idempotent. לוגיקת ה-deduplication שלנו מפחיתה עיבוד כפול ב-95% בהשוואה למימושים נאיביים. דוגמה ל-deduplication דרך Redis:
הצגת קוד deduplication
// Дедупликация через event_handler_id + временная метка $eventKey = md5($event . $dealId . $request->input('ts')); if ($redis->set("processed:{$eventKey}", 1, ['NX', 'EX' => 3600])) { ProcessBitrixEvent::dispatch($payload); // Если ключ уже есть — дубль, игнорируем } Bitrix24 מצפה ל-HTTP 200 תוך 5 שניות — תיעוד REST API.
איך להימנע מלולאות סנכרון?
בעיה קלאסית: המערכת החיצונית מקבלת // routes/api.php (Laravel) Route::post('/webhooks/bitrix24', function (Request $request) { // Валидация токена — быстро if (!validateBitrixToken($request->input('auth.application_token'))) { return response('Forbidden', 403); } // Кладём в очередь — быстро ProcessBitrixEvent::dispatch($request->all()); // Немедленно отвечаем return response('OK', 200); }); , מעדכנת את מסד הנתונים שלה, ואז שולחת עדכון חזרה ל-Bitrix24 — זה שוב מייצר // app/Jobs/ProcessBitrixEvent.php class ProcessBitrixEvent implements ShouldQueue { public $tries = 3; public $backoff = [60, 300, 900]; // 1 мин, 5 мин, 15 мин public function handle(): void { $event = $this->payload['event']; $dealId = $this->payload['data']['FIELDS']['ID']; // Теперь получаем полный объект $deal = $this->b24->call('crm.deal.get', ['id' => $dealId]); // ... обработка } } , ויוצר לולאה אינסופית. אנו מיישמים שלושה פתרונות:
דגל בעסקה
הגדרת שדה מותאם אישית ONCRMDEALUPDATE לפני כתיבה מהמערכת החיצונית, בדיקתו ב-handler — אם Y, דלג ואפס.
Hash של נתונים
השוואת ה-hash של הנתונים הנכנסים ל-hash האחרון שעובד — אם שווה, דלג.
חותמת זמן
אם האירוע נוגע לעדכון שלנו (חותמת זמן ≤ 2 שניות מאז הכתיבה האחרונה שלנו) — התעלם.
ניטור מסירה ומגבלות אירועים
לוג אירועים והתראות
Bitrix24 אינו מנהל לוג מסירה עבור מקבלי webhook חיצוניים. עליכם לנהל אותו בעצמכם. אנו יוצרים טבלה:
הצגת סכימת טבלת לוג
CREATE TABLE webhook_events ( id SERIAL PRIMARY KEY, event_type VARCHAR(64), entity_id INTEGER, received_at TIMESTAMP DEFAULT NOW(), processed_at TIMESTAMP, status VARCHAR(16) DEFAULT 'pending', error_message TEXT ); הגדירו ניטור webhook: אם לא מגיע אירוע // Дедупликация через event_handler_id + временная метка $eventKey = md5($event . $dealId . $request->input('ts')); if ($redis->set("processed:{$eventKey}", 1, ['NX', 'EX' => 3600])) { ProcessBitrixEvent::dispatch($payload); // Если ключ уже есть — дубль, игнорируем } תוך 10 דקות בשעות העבודה, סביר ש-Bitrix24 הפסיק לקרוא ל-handler. קבלו ייעוץ על הגדרת ניטור מהמהנדסים שלנו — נעזור להגדיר התראות ו-dashboards.
מאפייני אירועים
| אירוע | מאפיינים |
|---|---|
ONCRMDEALUPDATE |
מופעל על כל שינוי של כל שדה |
ONCRMDEALUPDATE |
לא מופעל בעת ייבוא דרך API עם UF_CRM_SYNC_LOCK=Y |
CREATE TABLE webhook_events ( id SERIAL PRIMARY KEY, event_type VARCHAR(64), entity_id INTEGER, received_at TIMESTAMP DEFAULT NOW(), processed_at TIMESTAMP, status VARCHAR(16) DEFAULT 'pending', error_message TEXT ); |
נתוני הקלטת שיחה זמינים באיחור של 5–30 שניות |
ONCRMDEALUPDATE |
לא כולל שינויים ב-checklist |
ONCRMDEALUPDATE |
רק עבור בוטים הרשומים דרך ONCRMDEALADD |
Bitrix24 On-Premise: אירועים מורחבים
התקנות on-premise כוללות אירועים ברמת PHP שאינם זמינים ב-REST API. לדוגמה, ניתן ליירט את האירוע לפני שמירת עסקה ולשנות את הנתונים:
הצגת handler לאירוע on-premise
\Bitrix\Main\EventManager::getInstance()->addEventHandler( 'crm', 'OnBeforeCrmDealAdd', [MyHandler::class, 'onBeforeDealAdd'] ); ניתן ליצור אירועים משלכם ממודול: DISABLE_PORTAL_ACTIVITY=Y.
מהם שלבי הפיתוח והעלויות?
תוכנית אינטגרציה שלב אחר שלב
- עיצוב: הגדרת רשימת האירועים, סכימת הנתונים, ארכיטקטורת ה-handler.
- נקודת קצה ותור: מימוש HTTP handler, Job, deduplication.
- לוגיקת עסקית: טיפול בכל סוג אירוע, קריאה למערכות חיצוניות.
- הגנה מפני לולאות: דגלי סנכרון, idempotency.
- ניטור: לוג אירועים, התראות, dashboard.
- בדיקות: סימולציית אירועים, בדיקות עומס.
| שלב | תוכן | משך |
|---|---|---|
| עיצוב | רשימת אירועים, סכימת נתונים, ארכיטקטורת handler | 2–3 ימים |
| נקודת קצה ותור | HTTP handler, Job, deduplication | 3–5 ימים |
| לוגיקת עסקית | טיפול בכל סוג אירוע, קריאה למערכות חיצוניות | 1–3 שבועות |
| הגנה מפני לולאות | דגלי סנכרון, idempotency | 2–3 ימים |
| ניטור | לוג אירועים, התראות, dashboard | 2–3 ימים |
| בדיקות | סימולציית אירועים, בדיקות עומס | 3–5 ימים |
סה"כ: בין 3 ל-7 שבועות תלוי במספר האירועים ובמורכבות הלוגיקה העסקית. עלות פרויקט טיפוסית נעה בין $5,000 ל-$15,000 תלוי במורכבות. אוטומציה יכולה לחסוך עד $10,000 בשנה בעבודה ידנית. אינטגרציה זו בדרך כלל מחזירה את ההשקעה תוך 6 חודשים דרך חיסכון בעבודה ידנית, מה שהופך אותה להשקעה חכמה לאוטומציה של תהליכים עסקיים.
מה כלול בעבודה
- תיעוד ארכיטקטורה
- קוד נקודת קצה (HTTP handler, queue job, deduplication)
- הגדרת תור וניטור (Redis, dashboard)
- מדריך פריסה
- הדרכת צוות
- תמיכה לאחר השקה (חודש)
אנו מציעים חבילה מלאה: תיעוד ארכיטקטורה, קוד נקודת קצה, הגדרת תור וניטור, מדריך פריסה, הדרכת צוות, תמיכה לאחר השקה. רקורד מוכח שלנו כולל למעלה מ-50 אינטגרציות Bitrix24 עם ניסיון של עשור. כל אירועי ה-CRM המרכזיים נתמכים, מה שמאפשר אוטומציה חלקה של תהליכים עסקיים.
בקשו הערכת פרויקט — המהנדסים שלנו ינתחו את הארכיטקטורה שלכם ביום אחד ויציעו את הפתרון האופטימלי. צרו קשר כדי לדון בפרטים.