Developing webhooks for Bitrix24

Webhook Development for Bitrix24

A deal moves to the "Paid" status — and within seconds an invoice appears in the accounting system, a delivery request is created in the logistics platform, and the client receives an SMS. Without webhooks, this would be either manual work or a polling loop checking for changes every minute. Webhooks are push notifications from Bitrix24 about events that have occurred in the system.

Inbound vs Outbound Webhooks

Bitrix24 has two types of webhooks that are often confused:

Outbound webhooks. Bitrix24 sends an HTTP request to your server when an event occurs. Configured through the interface or via the REST API event.bind. This is the primary tool for reacting to CRM events.

Inbound webhooks. An external service calls the Bitrix24 REST API without OAuth — using a URL with an embedded token. Used for simple integrations that do not require a full OAuth flow.

Configuring Outbound Webhooks via REST API

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

Full list of CRM events: ONCRMDEALCHANGE, ONCRMCONTACTCHANGE, ONCRMLEADCHANGE, ONCRMACTIVITYCHANGE, and others — more than 150 events in the documentation.

Deep Dive: Webhook Handler on the Application Side

The handler must respond to the Bitrix24 request quickly (within 5 seconds) and process data asynchronously. If the handler responds slowly or returns a non-200 OK status, Bitrix24 retries the request multiple times with exponential backoff.

// Route POST /b24/webhook/deal-stage
public function handleDealStage(Request $request): Response
{
    // 1. Verify signature (if configured)
    if (!$this->verifySignature($request)) {
        return response('Unauthorized', 401);
    }

    // 2. Dispatch job to queue and immediately return 200
    DealStageChangedJob::dispatch($request->all())->onQueue('b24-events');

    return response('OK', 200);
}

// 3. Job is processed asynchronously
class DealStageChangedJob implements ShouldQueue {
    public function handle(): void {
        $dealId  = $this->data['data']['FIELDS_AFTER']['ID'];
        $stageId = $this->data['data']['FIELDS_AFTER']['STAGE_ID'];

        if ($stageId === 'WON') {
            // Create invoice in the accounting system
            $this->accountingService->createInvoice($dealId);
            // Create shipment request in logistics
            $this->logisticsService->createShipment($dealId);
            // Send SMS to client
            $this->smsService->sendPaymentConfirmation($dealId);
        }
    }
}

Key principles: immediate 200 response, asynchronous processing, idempotency (re-processing a duplicate webhook must not create a duplicate record).

Signature Verification

Bitrix24 can pass an authorization token in the webhook (auth[access_token]). The handler must verify that the token belongs to the expected portal and application. For additional security, an IP whitelist can be added — Bitrix24 publishes a list of its IP addresses.

Storage and Monitoring

All incoming webhooks are logged in the myvendor_b24_webhook_log table:

• received time
• event type
• request body (with tokens masked)
• processing status (pending / processed / failed)
• number of attempts

The monitoring dashboard shows: queue of unprocessed events, events with errors, average processing time. When more than 50 unprocessed events accumulate — an alert is sent via email/Telegram to the administrator.

Replay Pattern

When an external system fails (e.g., the accounting system was unavailable), some webhooks may not have been processed. The module implements a replay capability: the administrator selects a date range and event type, and the system re-executes the handler for all events from the log.

Development Timeline

Before development, create an event map: which Bitrix24 event triggers which action in an external system. This allows you to estimate the scope of work and identify potential conflicts (one event triggering a chain of actions).