פיתוח Webhooks של Bitrix24: הגדרה, עיבוד, אינטגרציה

פיתוח Webhook ל-Bitrix24: הגדרה, עיבוד, אינטגרציה

עסקה עוברת לסטטוס "שולם" — תוך שניות, חשבונית מופיעה במערכת החשבונאות, בקשת משלוח נוצרת בפלטפורמת הלוגיסטיקה, ו-SMS נשלח ללקוח. ללא webhooks, זה היה עבודה ידנית או לולאת סקירה שבודקת שינויים כל דקה. Webhooks הם התראות push מ-Bitrix24 על אירועים במערכת. אנחנו, כמפתחים עם ניסיון של 5+ שנים, מבטיחים יישום אמין של תרחישים כאלה.

בממוצע, פורטל מקבל 50-100 אירועים בדקה בשעות השיא. עיבוד בזמן אמת של כל אחד מהם הוא קריטי לתהליכים עסקיים. ללא מערכת webhook מוגדרת כראוי, חברות נתקלות בעיכובים במשלוח הזמנות, חשבוניות כפולות ואובדן נתונים. אנחנו פותרים בעיה זו באמצעות דפוסי ארכיטקטורה מוכחים וסט הכלים של Bitrix24.

אילו בעיות Webhooks פותרים?

Webhooks הופכים תגובות לאירועים לאוטומטיות ללא מעורבות אנושית. משימות עסקיות עיקריות:

• סנכרון עסקאות CRM עם מערכות חשבונאות (1C, ERP)
• יצירת הזמנות אוטומטית בלוגיסטיקה (CDEK, דואר רוסי)
• שליחת הודעות ללקוחות (SMS, דוא"ל, Telegram)
• עדכון נתונים בלוחות מחוונים אנליטיים

מניסיון: בפרויקט אחד, אינטגרציה עם 1C דרשה עיבוד של 200 אירועים בדקה. יישמנו עיבוד אסינכרוני באמצעות RabbitMQ והשגנו זמן עיבוד מתחת לשנייה אחת. זה פי 10 מהר יותר מסקירה תקופתית, שהייתה לה עיכוב של 30-60 שניות.

Webhooks נכנסים מול יוצאים: מה ההבדל?

ל-Bitrix24 יש שני סוגים של webhooks שלעתים קרובות מבלבלים ביניהם:

Webhooks יוצאים מוגדרים דרך הממשק או REST API event.bind. Webhooks נכנסים הם כתובות URL עם token מוטמע שניתן להשתמש בהן כדי לקרוא ל-REST API של Bitrix24 ללא תהליך OAuth מלא. הבחירה תלויה בתרחיש: יוצאים לתגובה לאירועים, נכנסים לניהול חיצוני ממערכות צד שלישי.

איך להגדיר Handler ל-Webhook?

תהליך שלב-אחר-שלב להגדרת handler:

1. רשום מינוי דרך event.bind תוך ציון האירוע וכתובת ה-URL של ה-handler.
2. יישם נקודת קצה שמקבלת בקשות POST מ-Bitrix24.
3. אמת את החתימה (בדוק את ה-token לאימות ואת כתובת ה-IP).
4. העבר נתונים ל-handler אסינכרוני (דרך תור).
5. החזר HTTP 200 OK במהירות האפשרית.

דוגמה למינוי לשינוי שלב בעסקה:

$client->call('event.bind', [
    'event' => 'ONCRMDEALSTAGEID',
    'handler' => 'https://integration.mycompany.ru/b24/webhook/deal-stage',
    'auth_type' => 1,
    'options' => [
        'add_auth' => 'Y',
    ],
]);

הרשימה המלאה של אירועי CRM זמינים כוללת למעלה מ-150 שמות: ONCRMDEALCHANGE, ONCRMCONTACTCHANGE, ONCRMLEADCHANGE, ואחרים. הרשימה המלאה זמינה בתיעוד הרשמי של REST API.

למה Idempotence חשובה?

ה-handler של ה-webhook חייב להגיב במהירות (עד 5 שניות) ולעבד נתונים באופן אסינכרוני. אם התגובה איטית או לא 200 OK, Bitrix24 חוזר על הבקשה עם השהיה אקספוננציאלית. ללא idempotence, עיבוד חוזר יוצר כפילויות: למשל, חשבוניות כפולות או שתי הזמנות משלוח. Idempotence מבטיחה שקריאות חוזרות לא גורמות לתופעות לוואי.

public function handleDealStage(Request $request): Response
{
    if (!$this->verifySignature($request)) {
        return response('Unauthorized', 401);
    }

    DealStageChangedJob::dispatch($request->all())->onQueue('b24-events');

    return response('OK', 200);
}

class DealStageChangedJob implements ShouldQueue
{
    public function handle(): void
    {
        $dealId = $this->data['data']['FIELDS_AFTER']['ID'];
        $stageId = $this->data['data']['FIELDS_AFTER']['STAGE_ID'];

        // Проверка идемпотентности: событие уже обработано?
        if ($this->alreadyProcessed($dealId, $this->data['event_id'])) {
            return;
        }

        if ($stageId === 'WON') {
            $this->accountingService->createInvoice($dealId);
            $this->logisticsService->createShipment($dealId);
            $this->smsService->sendPaymentConfirmation($dealId);
        }
    }
}

איך להבטיח אמינות מערכת?

אימות חתימה

Bitrix24 עשוי להעביר token לאימות ($client->call('event.bind', [ 'event' => 'ONCRMDEALSTAGEID', 'handler' => 'https://integration.mycompany.ru/b24/webhook/deal-stage', 'auth_type' => 1, 'options' => [ 'add_auth' => 'Y', ], ]); ). ה-handler בודק שה-token שייך לפורטל הצפוי. לאבטחה נוספת, אנו מוסיפים רשימת IP מותרים — רשימת ה-IPs של Bitrix24 מפורסמת בתיעוד הרשמי.

רישום וניטור

כל ה-webhooks הנכנסים מתועדים בטבלת מסד נתונים (לדוגמה, public function handleDealStage(Request $request): Response { if (!$this->verifySignature($request)) { return response('Unauthorized', 401); } DealStageChangedJob::dispatch($request->all())->onQueue('b24-events'); return response('OK', 200); } class DealStageChangedJob implements ShouldQueue { public function handle(): void { $dealId = $this->data['data']['FIELDS_AFTER']['ID']; $stageId = $this->data['data']['FIELDS_AFTER']['STAGE_ID']; // Проверка идемпотентности: событие уже обработано? if ($this->alreadyProcessed($dealId, $this->data['event_id'])) { return; } if ($stageId === 'WON') { $this->accountingService->createInvoice($dealId); $this->logisticsService->createShipment($dealId); $this->smsService->sendPaymentConfirmation($dealId); } } } ):

• זמן קבלה
• סוג אירוע
• גוף הבקשה (עם מיסוך token)
• סטטוס עיבוד (ממתין / מעובד / נכשל)
• מספר ניסיונות

לוח המחוונים לניטור מציג: תור של אירועים לא מעובדים, אירועים עם שגיאות, זמן עיבוד ממוצע. כאשר מצטברים יותר מ-50 אירועים לא מעובדים, נשלחת התראה בדוא"ל או ב-Telegram למנהל המערכת.

דפוס Replay

אם מערכת חיצונית נכשלת (לדוגמה, מערכת החשבונאות לא זמינה), חלק מה-webhooks עשויים שלא לעובד. המודול מיישם replay: המנהל בוחר טווח תאריכים וסוג אירוע, והמערכת מבצעת מחדש את ה-handler עבור כל האירועים מהלוג.

מה כלול בעבודה

בהזמנת פיתוח webhook, אתה מקבל:

• מפת אירועים: ניתוח תהליכים עסקיים ומיפוי לאירועי Bitrix24
• פיתוח handler (נקודת קצה + תור אסינכרוני)
• הגדרת רישום וניטור
• תיעוד פריסה ותפעול
• הדרכת מנהלים (שעה אחת)
• תמיכה טכנית לחודש לאחר המסירה

לוחות זמנים ועלות

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

טעויות אופייניות בפיתוח Webhook

• חוסר idempotence → כפילות נתונים
• עיבוד סינכרוני → timeouts וניסיונות חוזרים
• התעלמות מאימות חתימה → פגיעות לבקשות מזויפות
• רישום לא מספק → קשה לנפות תקלות

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

צור קשר להערכת פרויקט שלך — נציע פתרון אופטימלי כולל. ניסיון של 5+ שנים ולמעלה מ-50 אינטגרציות מוצלחות מבטיחים איכות. הזמן פיתוח webhook וקבל פתרון מוכן תוך 2-3 שבועות.