Skip to content
← All articles
9 min read

Bitrix24 API integration: webhooks, OAuth, batching, and rate limit handling

Bitrix24 REST API integration relies on two authorization models: inbound webhooks for simple automations and local OAuth applications for backend services, paired with batch requests up to 50 commands and background queues tuned for leaky bucket throttling. Below, we break down creating leads and deals, safe data synchronization, handling plan-dependent rate limits, retry idempotency, and processing outbound events reliably.

Inbound webhooks vs OAuth applications: which should you choose?

Bitrix24 offers two primary ways to call its REST API: inbound webhooks and local OAuth 2.0 applications. Choosing the right mechanism determines system reliability during staff turnover and permission updates.

An inbound webhook is generated in the portal UI in minutes as a fixed URL containing an embedded secret key. Its primary vulnerability is tight coupling to a single employee account. Every action executes under that user's identity, meaning if the employee leaves or loses CRM access, the webhook breaks immediately. Furthermore, embedding the secret token in the URL complicates key rotation.

A local OAuth 2.0 application operates with standard client_id, client_secret, access, and refresh tokens. Background services refresh short-lived tokens automatically, while permissions are assigned at the application level by portal administrators. This keeps integrations operational regardless of organizational personnel changes.

  • Inbound webhook: suitable for rapid prototyping, internal scripts, and single-form lead capture without strict key rotation requirements.
  • OAuth application: essential for production microservices, ERP integrations, and core backend pipelines requiring total user independence.
  • Secret management: webhooks expose tokens inside URLs; OAuth applications keep credentials securely isolated in server configuration stores.
  • Access rotation: deactivating a webhook creator immediately breaks data flow; OAuth application credentials are easily renewed centrally by administrators.

Creating leads and deals via REST API: web forms, bots, and contact matching

Capturing inquiries from landing pages, web forms, and messaging bots is a core CRM integration workflow. In Bitrix24, lead creation uses crm.lead.add, while deals use crm.deal.add. First, identify your portal mode: classic CRM uses leads with subsequent conversion, whereas simple CRM creates deals and contacts directly.

Payloads require a title (TITLE), contact information, comments, and standard marketing tags: UTM_SOURCE, UTM_MEDIUM, and UTM_CAMPAIGN. The ASSIGNED_BY_ID field designates the responsible manager. Dynamic assignment is best handled inside your integration service based on shift schedules and team capacity rather than static CRM rules.

To prevent duplicate customer records, call crm.duplicate.findbycomm before creating deals. The method inspects normalized phone numbers and emails, returning IDs of matching leads, contacts, or companies. If a match exists, attach the new deal via CONTACT_ID without generating duplicate cards. Ingesting leads from messaging apps is covered in our guide to Telegram bot CRM integration.

  • Data normalization: clean phone numbers into E.164 format and convert email addresses to lowercase before deduplication.
  • Deduplication via crm.duplicate.findbycomm: attaches new deals to existing customer records, preserving interaction history.
  • Marketing attribution: map campaign parameters to native UTM fields for precise multi-channel performance tracking.
  • Dynamic assignment: calculate ASSIGNED_BY_ID in the integration layer based on real-time manager availability.

Reading and syncing data: pagination, filters, and selective field fetching

Data synchronization relies on list endpoints: crm.lead.list, crm.deal.list, crm.contact.list, and crm.company.list. The most common pitfall is requesting all fields without filtering. An empty select array forces the database to serialize every default and custom attribute, causing latency spikes and timeouts. Always declare an explicit list of required fields.

Standard Bitrix24 pagination uses the start offset parameter, advancing in steps of 50 records. Responses return a next property pointing to the subsequent page. However, for datasets containing tens of thousands of records, deep offset scanning severely degrades database performance on the CRM server.

For reliable incremental synchronization, adopt primary-key filtering: order records ascending by identifier (ID: ASC) and filter for IDs greater than the last processed cursor (>ID: last_id). The service pulls records in predictable slices without skipping entries during concurrent writes. Store sync cursors in PostgreSQL to resume seamlessly after restarts.

Batch requests: packing up to 50 commands and understanding their limits

Sending dozens of individual HTTP requests introduces excessive network overhead. The batch method bundles up to 50 independent or dependent REST commands into a single HTTP POST request, cutting network latency dramatically.

The endpoint enforces a strict boundary: a batch payload cannot exceed 50 commands. Commands beyond the 50th come back with the error ERROR_BATCH_LENGTH_EXCEEDED. Outgoing job queues must partition payloads into slices of at most 50 commands.

Batching supports referencing results between commands using the $result macro. This enables multi-step workflows in a single network round trip: creating a contact (cmd_contact), a company (cmd_company), and linking both to a deal (cmd_deal) by passing $result[cmd_contact] into CONTACT_ID.

Batching eliminates network handshakes but does not bypass server execution quotas. Batching cuts HTTP round trips, but the methods inside still consume the portal's resource limits.

  • Batch size boundary: strictly up to 50 commands; commands beyond it return ERROR_BATCH_LENGTH_EXCEEDED.
  • Result linking: the $result[cmd] syntax passes generated entity IDs across dependent commands in a single HTTP call.
  • Error handling: check the result of every command in the response, not only the HTTP status of the whole batch.
  • Resource quotas: batching saves network round trips, but method execution time counts against portal rate limits.
  • Heavy methods: keep batches smaller for slow operations and watch response times.

Rate limiting: navigating the Bitrix24 leaky bucket algorithm

Bitrix24 regulates API traffic using the leaky bucket algorithm. Incoming requests fill a virtual bucket of fixed capacity that drains at a steady processing rate. If request volume outpaces processing capacity, the bucket overflows, and excess requests are immediately rejected with rate limit errors.

Bucket capacity and drain speed depend on your Bitrix24 subscription plan and deployment edition. Entry tiers have tighter constraints, while enterprise tiers offer expanded headroom. Consequently, integration code must never rely on hardcoded requests-per-second values; the architecture must adapt dynamically.

Firing concurrent worker threads without pacing quickly overflows the bucket and the portal starts returning rate-limit errors. A robust Go backend should implement a local token bucket rate limiter (using x/time/rate). Outbound calls are paced smoothly through an internal queue, preventing the portal from enforcing harsh throttling.

Error handling, idempotency, and retrying failed requests

Network disruptions during entity creation are routine operational events. A CRM server might write a lead successfully, but a dropped connection prevents the HTTP 200 response from reaching your service. If your worker blindly retries the call, duplicate leads are created.

The answer is strict idempotency, detailed in our guide to API idempotency and retries. Generate a unique UUID for each inquiry and save it in a custom Bitrix24 field (such as UF_CRM_EXTERNAL_ID). On timeout, query the CRM by this UUID before retrying creation to prevent duplicates.

Retry strategies must separate transient errors from permanent validation failures. Transient issues (rate-limit errors, 5xx responses and network timeouts) should be retried using exponential backoff with randomized jitter. Permanent errors (invalid data, missing permissions) should be diverted to a Dead Letter Queue for engineer review. For queue design patterns, see our guide on background jobs and queues in Go.

  • External UUID tracking: storing inquiry UUIDs in a custom CRM field ensures idempotent retries without duplicating deals.
  • Exponential backoff with jitter: randomized retry pauses prevent self-inflicted traffic surges after brief API disruptions.
  • Error classification: transient network faults retry automatically; invalid schema errors are flagged for manual inspection.
  • Local PostgreSQL queue: persists incoming inquiries before transmission, guaranteeing zero data loss during CRM outages.
  • Queue observability: monitoring queue latency and rate-limit errors provides early warnings before rate limits turn critical.

Outbound events: receiving webhooks and validating signatures

Bi-directional synchronization requires reacting to manager actions inside CRM, such as deal stage transitions or contact updates. Subscriptions are registered via the event.bind API method or configured manually through portal outbound webhook settings.

When an event triggers (such as ONCRMDEALUPDATE), Bitrix24 delivers a POST payload containing event data and an authorization token (application_token). Verifying this token against your stored secret is critical: rejecting unverified requests protects your internal endpoints against forged events, following principles from webhook security and signatures.

Webhook receivers must deliver immediate responses. The handler validates the token, pushes the payload into an internal queue, and instantly returns HTTP 200 OK. Never execute heavy processing synchronously in the receiver: a slow handler risks timeouts and lost events.

Integration architecture: when you need a dedicated Go backend

Simple setups handling dozens of leads daily often start with off-the-shelf no-code tools. In our review of n8n vs custom code, we explored their practical boundaries. As transaction volume scales, no-code connectors struggle with leaky bucket throttling, lack robust deduplication, and drop data during network hiccups.

A custom Go backend becomes necessary when coordinating multi-system enterprise environments. A typical architecture links web storefronts, customer mobile apps, CRM, and ERP systems. This requires robust inventory synchronization aligned with 1C integration methods and financial data pipelines following CRM and ERP integration practices.

A custom Go middleware layer serves as a resilient buffer: smoothing traffic bursts, pacing API calls, and guaranteeing delivery for every lead. Anaxita designs and builds reliable enterprise pipelines under our system integrations service.

  • No-code platforms: suitable for initial prototypes, low volumes, and straightforward linear flows without strict SLA needs.
  • Custom Go service: necessary for high throughput, complex deduplication logic, multi-system orchestration, and strict resilience.
  • Protective middleware: shields internal services from traffic surges, paces calls within rate limits, and secures API secrets.
  • Comprehensive audit log: writes all raw payloads to PostgreSQL for transparent debugging and auditability.
Questions

FAQ

Didn't find an answer — ask on the call or in Telegram.

How does Bitrix24 API integration work for leads and deals?

Bitrix24 integration operates via REST API endpoints such as crm.lead.add and crm.deal.add. Inquiries are first saved in a local backend database, verified against existing contacts using crm.duplicate.findbycomm, enriched with UTM marketing parameters, and dispatched to the CRM. A background worker regulates request pacing to respect rate limits and handles retries automatically during network disruptions.

What is the difference between an inbound webhook and an OAuth app in Bitrix24?

An inbound webhook is linked to an individual Bitrix24 user, exposes its secret key directly in the request URL, and stops functioning if the user leaves the company. A local OAuth application operates with client credentials and automatic token refresh, manages scoped permissions centrally, and provides the security and isolation required for production microservices.

How do batch requests work in the Bitrix24 REST API?

The batch endpoint bundles up to 50 REST commands into one HTTP POST request. Commands can reference results from previous steps using the $result macro. Commands beyond the 50th end with an ERROR_BATCH_LENGTH_EXCEEDED error. While batching reduces HTTP network latency, the methods inside still count toward the portal limits.

How do you avoid rate-limit errors from the Bitrix24 REST API?

Bitrix24 regulates requests using a leaky bucket algorithm whose parameters depend on your subscription plan. To avoid them, your integration service should implement an internal rate limiter, buffer outbound requests in a persistent queue, and apply exponential backoff with randomized jitter whenever throttling responses are detected.

How do you prevent duplicate deals when network timeouts occur?

Assign a unique UUID to each inquiry and store it in a custom Bitrix24 field. If a network timeout occurs during deal creation, the retry worker first queries the CRM for that external UUID. If the deal already exists, the worker updates local state without submitting a duplicate creation request.

How should a backend handle outbound webhooks from Bitrix24?

The receiving endpoint must verify the incoming authorization token, immediately return an HTTP 200 OK response, and push the payload into a persistent queue for asynchronous processing. Synchronous heavy processing in the webhook handler risks exceeding connection timeouts, which can lose events.

Related service

CRM, ERP and API integrations built for your workflows

When teams copy data between systems by hand, delays and mistakes become part of the process. We automate the exchange and make its status visible to the people running it.

Learn about the service
Other articles
Contact

Shall we discuss your task?

Thirty minutes on a call — and you understand the architecture, timeline and engagement format. No obligations.

Or message us on Telegram →Follow our Telegram channel →

Enter your Telegram or email so we can reply.

We reply within 15 minutes.