REST application Bitrix24: where the integration breaks
A Bitrix24 REST application almost never fails "on its own" — it breaks at the junction with the platform.
The portal responds to a request in fractions of a second, but as soon as a handler goes into a heavy query over deals or file export, the integration timeout triggers: the connection drops, the transaction is left in a half-state, and a duplicate or a lost entity appears in the CRM.
Then the discrepancy accumulates silently — it is noticed only during report reconciliation, when restoring the chain of events costs more than building it anew.
The second source of failures is request limits. The platform restricts the rate of calls to the portal and to a method, and during batch synchronization the application hits the ceiling: some calls come back with a rejection, some with a delay.
If the code has no queue with retries and no quota accounting, event loss becomes regular: webhooks do not arrive, changes to tasks and invoices are not pulled in, and the business sees a "frozen" funnel.
The third class of failures is update failures.
Bitrix24 changes method contracts and application moderation rules, and code that passed validation yesterday stops meeting the requirements: some fields disappear from the response, the event format changes, permission checks get stricter.
Without versioning and a set of contract autotests, such an update is rolled out to production unnoticed.
Separately, there is the matter of permissions and access scope: an application that requests excessive permissions does not pass Marketplace moderation, while missing permissions cause rejections on half of the methods.
Below we break down how these four scenarios are closed at the architecture level, rather than with patches in handlers.
What a correctly designed application provides
Application response speed is determined not by server capacity, but by how many calls to external services it makes per user request.
When a handler first pulls an entire reference dataset, then refines each record separately, response time grows linearly with data volume and, on real exports, stretches into tens of seconds.
We design the exchange so that a typical action involves the minimum number of calls, while heavy queries go into background jobs: the interface responds immediately, and data is loaded as it becomes ready.
Resilience to rate limits is the other half of the same task. External services throttle request frequency, and an application that doesn't account for this starts receiving rejections in batches.
A queue with retries and increasing backoff, separation of priority and background operations, and a local cache of reference data — all of this turns rejections from an outage into a normal mode: some requests simply execute a bit later, without losing the result.
Event loss is the most expensive class of failure, because it is discovered through data discrepancies rather than an error in the log. We record every incoming and outgoing event, store its state, and can replay what was missed after a restart or network interruption.
With such a loop, the share of lost events is isolated cases that are visible in monitoring immediately, rather than surfacing a month later during reconciliation.
Recovery time after a failure depends on how ready the application is for a restart. Idempotent handlers, saved checkpoints, and a clear reload order allow the integration to be brought up without manual reconciliation and re-entry of data.
Instead of "we spent two days bringing it up and reconciling manually," you get a predictable restart, after which the system catches up on what was missed on its own.
The bottom line: the stability of the integration stops depending on how lucky the day turned out to be. We break down how this is addressed at the application architecture level.
Integration methods: inbound webhooks, local and distributed applications
The choice of connection method determines not only the amount of code, but also how the solution will live on: who stores the credentials, what happens when the portal is updated, and how much manual work remains when handing over to the client. Below are three real options that are chosen between at the start of integration.
| Option | When it fits | Limitations |
|---|---|---|
| Inbound webhook | Quick exchange with a single external service, prototype, one-time export | Permissions are set once and are not differentiated by user, the token lives in plain text, there is no event logic or call queue |
| Local application | Integration for a specific portal: its own permissions, interface inside Bitrix24, exchange with internal systems | Installed manually on each portal, updates and fixes are delivered separately, no listing in the catalog |
| Distributed application | A product for many clients, sale or mass installation via the Marketplace | Requires passing moderation, versioning, support for multiple editions and access revocation scenarios |
Connection scenarios
A webhook covers tasks where a single channel in one direction is needed: receive a request from the website, return the deal status, export a reference list.
As soon as events, permissions for different roles and retries on failure appear — the webhook starts to accumulate workarounds, and it gets rewritten into an application.
A local application is chosen when the integration is tied to a single portal and the customer's internal systems. A distributed one — when the solution must be installed at many clients and updated centrally.
Integration limitations
The key difference is in the permission model and the lifecycle. With a webhook, access is not revoked granularly and is not logged per user; with an application, there is a scenario for installation, granting and revocation of permissions.
Hence the different support cost: fixing a webhook is a one-time effort, fixing a distributed product is a release with backward compatibility.
We analyze your scenario and select the option that won't have to be rewritten six months later.
Stages of REST application development and implementation
Work proceeds in iterations: each subsequent one builds on the artifacts of the previous one, so hidden dependencies surface at the beginning rather than at acceptance. Below is the sequence we follow when running a project.
- Integration audit. We build a map of current exchanges: which systems already send and receive data, where entities are duplicated, which calls bypass standard mechanisms. We record failure points and bottlenecks under load.
- Interaction schema. We agree on the data model and scenarios: which entities the application creates, what it reads from the portal, which events it subscribes to. The output is a flow diagram and a list of methods with request and response formats.
- Permission setup. We delineate access by roles and visibility scopes, determine what the application does on behalf of the user and what it does on behalf of a service account. We separately describe behavior when permissions are revoked.
- Implementation and scenario verification. We build the application and run through the main and edge cases: empty responses, repeated calls, connection drops, concurrent write conflicts. We log errors so that the entire call chain can be reconstructed from a record.
- Test environment and load. We deploy a copy of the portal, verify application installation and removal, behavior during updates, and response under parallel requests. We observe how the solution behaves when an external system is unavailable.
- Handover to operation. We publish to the Marketplace, prepare the listing and instructions, and hand over the update regulations and the procedure for rolling back to the previous build. Separately — a diagnostic checklist for first-line support.
Each stage is closed with an artifact: an integration map, a schema, a permission matrix, a scenario run report, regulations. This way, at handover the customer's team is left not only with a working application but also with an understanding of how to maintain it.
What the customer receives after implementation
Implementation ends not with a demonstration of a working application, but with the handover of a package that your team can use to operate it, develop it further, and pass it on to new engineers. Below is what exactly remains in your hands.
- Application and environment configurations — configuration files for the local stand, test, and production environments: portal connection parameters, integration keys, environment variables. Deployment is repeatable on a clean machine without "tweaking from memory."
- Interaction diagrams — data flow diagrams between the application, the portal, and external systems: which REST methods are called, where tokens are stored, how webhooks and repeated event deliveries are handled.
- Access policies — a matrix of permissions by portal roles and data visibility scopes, rules for issuing and revoking tokens, restrictions on outbound requests. An auditor can see who has access to which data.
- Operational regulations — the procedure for updating the application, rotating keys, responding to an external service failure, and a rollback plan to the previous build while preserving data.
- Support instructions — what to look for in the logs during typical failures, how to reproduce the problem on the test environment, whom to contact and with what data. First-line support resolves the incident without a developer.
- Code and API documentation — a description of modules, extension points, and public methods so that further development can be carried out by another team.
- Migration and backup scripts — reproducible transfer of settings and data between environments, a verified recovery scenario.
- Acceptance scenarios — a set of checks that confirm functionality after each update.
Such a package removes the main risk: the application stops being a "black box" belonging to a single contractor. Describe your task — we will come back with an estimate and a plan for the form in which we will hand over the artifacts in your specific case.
Case study: how we eliminated event loss in a REST application
The client came with a symptom, not a diagnosis: the integration with Bitrix24 "sometimes doesn't work." In reality, events from the queue were being lost during load spikes — the webhook went out, but the handler crashed on a timeout, and no one knew about it.
The share of lost events reached 8%, and managers closed the discrepancies between the CRM and the accounting system by hand: reconciliation took the team up to two days a week.
What it was before
Processing happened synchronously at the moment of the event: the external service responded slowly, the request hung, there were no retries, and errors settled only in the application logs.
Response time at peak reached 12 seconds, some operations dropped off due to timeout, and they could only be restored by manually re-running them. There was no idempotency at all — repeated delivery created duplicate records.
What we changed
We separated event intake and event processing into different loops: the application accepts an event, records it in the queue, and responds immediately, while parsing happens asynchronously with a concurrency limit.
We added an idempotent key to each event so that repeated delivery wouldn't spawn duplicates, and set up retries with increasing delay — a failing handler returns to work on its own, without human involvement.
Separately, we built a log of unprocessed events: whatever couldn't be parsed after all attempts goes into a separate list with the reason, rather than dissolving into the logs.
Metrics after
| Indicator | Before | After |
|---|---|---|
| Share of lost events | up to 8% | less than 0.1% |
| Response time at peak | up to 12 s | consistently up to 1 s |
| Manual operations per week | ~2 days of reconciliation | isolated investigations |
Fixing failures stopped being routine: an engineer looks at the log of unprocessed events once a week, rather than sorting out discrepancies for each client. The application passed moderation and is updated in the Marketplace without stopping clients' operations.
How is a marketplace app different from a local app?
A marketplace app is a product that goes through moderation and is published in the Bitrix24 Marketplace, after which any portal client can install it.
A local app lives inside a single portal: it is installed manually, via a direct link to the handler, and does not go beyond a specific installation. This is where all further requirements diverge — for updates, support, and security.
The key difference lies in the update model. A marketplace app is updated centrally: you publish a new version, and it rolls out to all installations through the Marketplace's standard mechanism.
A local app is updated on a case-by-case basis — separately on each portal, and if the client made changes to the code, the update may conflict with them.
That is why in a marketplace app, backward compatibility and data migrations are planned in advance, while in a local app it is enough to reach an agreement with a single customer.
Security in a marketplace app is checked more strictly. The app works with data from many portals, so access is requested to a minimum, tokens are stored in isolation, and handlers validate incoming requests.
A local app often inherits the rights of whoever installed it — that is sufficient within a single environment, but such an approach will not pass for publication in the Marketplace.
Support is also structured differently. A marketplace app requires a support line for all clients, a unified error log, and a predictable release cycle for versions.
A local app is serviced on a targeted basis: changes are made for a specific portal, and regression is tested on its own data.
The choice between the formats is a choice between scale and speed: a marketplace app provides reach and repeatable revenue, a local app provides a fast result for a single task.
Common technical concerns in development
Before development starts, the same questions almost always come up: will the application handle request limits, what happens after the next platform update, will the integration break, and who is responsible for support after launch. Below are straight answers, without vague wording.
Will we hit Bitrix24 request limits?
Yes, limits exist, and they cannot be ignored. We build in error handling with retries and increasing backoff, move heavy operations into background jobs, and cache what does not change every minute.
In practice, this ensures stable operation even under peak load: the application does not "crash" during a bulk export but calmly works through the queue.
What happens after a platform update?
The platform is updated regularly, and some methods become deprecated. We build the application on public, documented calls and isolate them in a separate layer — when changes occur, we fix one place rather than the entire application. This reduces the risk of sudden breakages and the cost of modifications after the next release.
How is compatibility and data security ensured?
The application operates with the permissions it has been granted and does not request anything extra. Tokens are stored in a secure form, access is role-based, and sensitive data is not written to logs.
We test compatibility across different portal editions so that behavior is predictable for all users.
Who supports the application after launch?
We hand over the source code, the integration schema, and deployment instructions. After that, support is possible under an agreed procedure: we track platform changes, update dependencies, and resolve incidents. You are not left alone with the application after delivery.
Describe your task — we will come back with an estimate and a work plan.
Let's discuss your task and come back with an estimate
To make the estimate substantive rather than pulled out of thin air, we need to understand the scenario: which entities the application reads from and writes to Bitrix24, whether it works through incoming webhooks or a full-fledged OAuth flow, whether background jobs and event handling are needed.
This determines the scope of work for the Bitrix24 REST application — from a thin wrapper over a couple of methods to a service with queues, retries, and data synchronization.
Send us a description of the task in free form: what should happen, who the users are, which portal sections are involved, whether there are existing developments or a ready-made technical specification.
If there is no technical specification, we will put it together on a call, fix the boundaries and integration points.
After the review, you will receive:
- a work plan by stages: analysis, design of the authorization flow, development, testing on a test portal, publication in the Marketplace;
- an effort estimate broken down by blocks and the assumptions it depends on;
- timelines for each stage, taking into account the Marketplace review;
- team composition — who leads the architecture, who writes the code, who is responsible for testing and publication;
- risks and options for closing them: method limits, behavior when a token is revoked, data migration;
- support format after release: updates for API changes, error monitoring, response to requests.
The estimate and plan are a working document you can use to make a decision. Describe the task in any convenient form: text, voice, or on a call. We will come back with a breakdown, timelines, and cost — with no obligations on your side.