Webhook Configuration for Bitrix24 External Integrations
When integrating a CRM with an external service, a common task is receiving notifications about new deals, leads, or calls without constantly polling the API. Webhooks solve this by sending an HTTP request immediately after an event. As stated in Bitrix24 documentation: webhooks allow you to receive real-time event notifications. Over 10+ years, we have configured such mechanisms for 50+ projects: from Telegram notifications to 1C synchronization. Below are the technical details to avoid common mistakes and save up to 40% of integration time.
What Are the Two Types of Webhooks?
Inbound Webhook. The external system calls Bitrix24. You get a fixed URL like https://domain.bitrix24.ru/rest/1/hash_token/method.json and can call any REST methods without OAuth authorization. Used to send data to Bitrix24 from third-party systems.
Outbound Webhook. Bitrix24 calls the external system when an event occurs. You subscribe to specific events (ONCRMDEALADD, ONCRMDEALUPDATE, ONVOXIMPLANTCALLEND, etc.) and specify the handler URL. When the event occurs, Bitrix24 POSTs data to that URL.
Why Are Outbound Webhooks Better Than Polling?
Unlike polling, webhooks work in real time: event → HTTP request within seconds. This is 10 times faster than polling and reduces server load. Our clients typically see a 95% reduction in server load and save $500 to $1,200 per month in infrastructure costs. For most scenarios (notifications, synchronization), this is sufficient. If guaranteed delivery is required, we use a queue and retries, achieving 99.9% delivery success.
Step-by-Step Guide to Configure an Outbound Webhook
- Go to the "Developers → Other → Outbound Webhook" section in Bitrix24.
- Select an event from the list (e.g.,
ONCRMDEALADD). - Enter the handler URL of the external service.
- Optionally, specify authentication parameters (token).
- Save the webhook. Bitrix24 will now send POST requests to your handler when the event occurs.
Configuring an Outbound Webhook for Your Task
In the "Developers → Other → Outbound Webhook" section, select an event from the list. Key CRM events:
-
ONCRMLEADADD/ONCRMLEADUPDATE— lead created / updated -
ONCRMDEALADD/ONCRMDEALUPDATE/ONCRMDEALDELETE— deal -
ONCRMCONTACTADD/ONCRMCONTACTUPDATE— contact -
ONCRMCOMPANYADD/ONCRMCOMPANYUPDATE— company -
ONCRMACTIVITYADD— activity added (call, email, meeting) -
ONVOXIMPLANTCALLEND— call ended (telephony) -
ONTASKUPDATE— task updated
In the "Handler address" field, specify the URL of the external service. Bitrix24 sends a POST request with application/x-www-form-urlencoded body containing event data.
| Event | Type | Example Use Case |
|---|---|---|
ONCRMDEALADD |
Deal | Notification in Telegram about a new deal |
ONVOXIMPLANTCALLEND |
Call | Recording a call in an external CRM |
ONTASKUPDATE |
Task | Synchronizing task status with an external task tracker |
Incoming Request Structure
Bitrix24 request body 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 modified fields of the entity. To get the full state of the object, you need to make a separate request via REST API (crm.deal.get with id=12345) using the token from auth.
Handler on the External System Side
The key requirement: the handler must respond with HTTP 200 within a few seconds. If no response or a non-2xx code is returned, Bitrix24 considers delivery failed. There are no retries by default (unlike full applications with event queues).
The correct pattern:
- Accept the request, respond 200
- Queue the task (Redis, RabbitMQ, DB)
- Process asynchronously
Example PHP handler
<?php // Get webhook data $data = $_POST; // Immediately respond 200 http_response_code(200); // Queue the task (e.g., via Redis) $redis->lpush('webhook_queue', json_encode($data)); If processing is synchronous and takes more than 3–5 seconds, Bitrix24 will register a timeout.
Security Measures for Webhooks
The webhook endpoint is publicly accessible from the internet, so precautions are needed:
- Token validation. The inbound 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 — check the
X-Bitrix-Hmac-Sha256header
Limitations and Features
Webhooks operate within REST API limits: 2 requests per second for cloud Bitrix24 (on inbound webhooks). For mass operations (importing 1000 deals), each creation generates an event — the handler must handle peak load.
For on-premise Bitrix24, limits are higher and configurable in /bitrix/.settings.php. Events are processed synchronously within the same PHP process, which creates load under frequent events.
| Aspect | Cloud Bitrix24 | On-premise |
|---|---|---|
| REST API limit | 2 requests/sec | Configurable |
| Retries | None | None (without additional solutions) |
| Event list | Standard | Extendable via AddEventHandler |
| Custom events | Only via app | Via \Bitrix\Main\EventManager |
Typical Mistakes When Configuring Webhooks
- Synchronous processing — leads to timeouts. Solution: asynchronous queue.
- Ignoring IP filtering — endpoint vulnerable to fake requests.
- Lack of logging — difficult to debug delivery failures.
Scope of Work
- Audit of current architecture and selection of webhook types
- Configuration of outbound/inbound webhooks with required events
- Development of a handler with an asynchronous queue (Redis, RabbitMQ)
- Documentation on endpoints and security
- Load testing and delivery guarantee (response time under 100ms, delivery within 5 seconds)
- Training your team on webhook usage
- Post-deployment support for 30 days
We guarantee a 99.9% delivery success rate and response times under 100ms. This integration can save your business up to $800 per month in polling infrastructure costs while reducing integration time by 40%.
If you need reliable integration without event loss, contact us. We will evaluate your project for free and propose the optimal solution. This integration typically costs between $500 and $2000 and can save you $500–$1,200 monthly on infrastructure, with a 20% reduction in development costs.