Setting up webhooks for external Bitrix24 integrations

Configuring Webhooks for External Bitrix24 Integrations

A webhook is a mechanism where Bitrix24 itself notifies an external system about an event without forcing it to constantly poll the API. A new deal, stage change, incoming call—Bitrix24 sends an HTTP request to the specified URL within seconds. This is the primary tool for building integrations without developing a full-fledged application.

Two Types of Webhooks

Incoming webhook (Inbound webhook). An external system calls Bitrix24. You receive a fixed URL like https://domain.bitrix24.ru/rest/1/token_hash/method.json and can invoke any REST methods without OAuth authorization. Used to send data to Bitrix24 from third-party systems.

Outbound webhook (Outbound webhook). Bitrix24 calls an external system when an event occurs. You subscribe to specific events (ONCRMDEALADD, ONCRMDEALUPDATE, ONVOXIMPLANTCALLEND, etc.) and specify the handler URL. Upon event occurrence, Bitrix24 POST-s the data to this URL.

Setting Up Outbound Webhooks

In the "Developers → Other → Outbound Webhook" section, select an event from the list. Primary events for CRM:

• ONCRMLEADADD / ONCRMLEAD UPDATE — lead created / updated
• ONCRMDEALADD / ONCRMDEALUPDATE / ONCRMDEALDELETE — deal
• ONCRMCONTACTADD / ONCRMCONTACTUPDATE — contact
• ONCRMCOMPANYADD / ONCRMCOMPANYUPDATE — company
• ONCRMACTIVITYADD — activity added (call, email, meeting)
• ONVOXIMPLANTCALLEND — call completed (telephony)
• ONTASKUPDATE — task update

In the "Handler Address" field, enter the external service URL. Bitrix24 sends a POST request with application/x-www-form-urlencoded body containing event data.

Incoming Request Structure

The request body from Bitrix24 contains:

event=ONCRMDEALUPDATE
&auth[access_token]=...
&auth[domain]=domain.bitrix24.ru
&data[FIELDS][ID]=12345
&data[FIELDS][STAGE_ID]=WON

The data[FIELDS] field contains the entity's modified fields. To obtain the complete object state, make a separate REST API request (crm.deal.get with id=12345) using the token from auth.

Handler on the External System Side

Critical requirement: the handler must return HTTP 200 within seconds. If no response arrives or the code differs from 2xx—Bitrix24 considers delivery failed. There are no retry attempts by default (unlike full applications with event queues).

Correct pattern:

1. Receive request, respond with 200
2. Queue task (Redis, RabbitMQ, database)
3. Process asynchronously

If processing is synchronous and takes more than 3–5 seconds—Bitrix24 records a timeout.

Security

A webhook endpoint is publicly accessible from the internet—this must be considered. Protection measures:

• Token validation. The incoming webhook URL contains a token—validate it on the handler side
• IP whitelist. Allow requests only from Bitrix24 IP addresses (list published in documentation)
• HMAC signature. For local applications, request signing is available—verify the X-Bitrix-Hmac-Sha256 header

Limitations and Features

Webhooks operate within REST API limits: 2 requests per second for cloud Bitrix24 (on incoming webhooks). During mass operations (importing 1000 deals), each creation generates an event—the handler must handle peak load.

For on-premise Bitrix24, limits are higher and configured in /bitrix/.settings.php. Events are processed synchronously within the same PHP process, creating load during frequent events.

Webhooks are a quick way to connect Bitrix24 with an external system without complex infrastructure. For simple scenarios (Telegram notification on new deal, synchronization with Google Sheets), this is sufficient. For complex integrations with delivery guarantees and error handling, full architecture with queue and application is required.