Developing Bitrix24 Marketplace Applications: OAuth, REST, Webhooks

Imagine you have developed an application for Bitrix24, passed moderation, and published it on the marketplace. A week later, complaints arrive — half of the clients have broken synchronization, and the application returns 403 on crm.deal.list. Turns out the 'Basic' plan does not grant CRM permissions, and you did not include a check. Or a webhook stops responding — the handler got unbound, data lost. These scenarios are consequences of typical mistakes that can be avoided during the architecture phase. The problem is that standard templates and unchecked errors are the main reasons for moderation rejections and client loss.

We have implemented over 50 custom Bitrix24 applications for the marketplace over 5 years — from simple widgets to multi-tenant Bitrix24 solutions. We know how to create a stable product that won't let clients down. We specialize in designing robust applications that pass moderation on the first try. Our experience helps avoid pitfalls related to tariff restrictions and error handling. Development cost starts at $3,000 for a simple widget and can go up to $15,000 for complex multi-tenant solutions. The investment pays off through savings on support and rework — typically reducing support time by 40% and handling over 10,000 webhooks per hour with proper async processing.

What Types of Applications Are There?

Embedded applications work in an iframe via the placement API. Placement points: CRM_LEAD_DETAIL_TAB, TASKS_TASK_VIEW_TAB, CALL_LIST, and dozens of others. Widgets are embedded via BX24.placement.call() for small actions: a button in a card, a panel in chat. Applications with a custom interface open in a separate tab — more UX freedom, but the user leaves the context. Bots and chat applications use imbot.* and imsetting.* methods and have their own handler.

Comparison:

OAuth 2.0 in Bitrix24 Applications

Authorization uses OAuth 2.0 with authorization code. Flow:

1. User installs the application → redirect to redirect_uri with code.
2. Application exchanges code for access_token and refresh_token via https://oauth.bitrix.info/oauth/token/.
3. access_token lives 1 hour, refresh_token lives 180 days.
4. Tokens are stored in your DB, tied to member_id.

For server-to-server, use grant_type=client_credentials — available for 'Application' type apps. member_id is critical: all data in the DB is partitioned by it, otherwise one company's data might leak to another.

Official Bitrix24 REST API OAuth documentation

Bitrix24 REST API: Working with Data

The Bitrix24 REST API is not classical REST. Methods are called via POST to https://{portal}.bitrix24.ru/rest/{method} with form-data or JSON. Pagination uses start, limit of 50 records. To get all, loop with next.

Popular groups:

• crm.lead., crm.deal., crm.contact., crm.company. — CRM
• tasks.task.*, task.item.list — tasks
• disk.folder., disk.file. — files
• im.message.add, imbot.message.add — messages
• user.get, user.search — users
• placement.bind — registration of placement points

Batch: send up to 50 requests via batch. Batching is 50 times faster than sequential requests.

POST /rest/batch { "halt": 0, "cmd": { "get_deal": "crm.deal.get?id=123", "get_contact": "crm.contact.get?id=456", "get_company": "crm.company.get?id=789" } } 

Webhook Handling Without Data Loss

Subscribe to events via event.bind. When an event occurs, Bitrix24 makes a POST to the handler URL. Important details:

• Handler must respond within 5 seconds.
• After 3 unsuccessful deliveries, the handler is unbound.
• For heavy processing, use a queue: accept the webhook, put it in a queue, respond 200, process asynchronously.

Available events: ONCRMLEADADD, ONCRMDEALUPDATE, ONTASKUPDATE, ONIMMESSAGECHAT, ONUSERADD, and hundreds more.

Example: In a multi-tenant CRM app, we reduced sync time from 30 seconds to 3 seconds by implementing event-driven Bitrix24 webhooks with an async queue — a 90% improvement.

Placements

Registration of placement is done during installation via placement.bind. It attaches to an interface point and passes context: entity ID, type, user permissions.

BX24.placement.getInterface(function(data) { console.log(data); }); 

Connect //api.bitrix24.com/api/v1/ and call BX24.init() before accessing the API. In an iframe, use localStorage or postMessage.

Dealing with Tariff Limitations

REST methods are not available on all tariffs. crm.* — from certain plans, telephony.* — with telephony feature, tasks.* — with the 'Tasks' module. Upon installation, check availability via app.info and profile. Explicitly inform the user if functionality is unavailable. Do not allow unhandled 403s.

Application Data Storage

Bitrix24 provides a key-value store app.option.set/get (limit ~32KB). For serious data, you need your own DB. For user settings, use user.option.set/get on the portal side.

Development Timeline

What's Included

• Requirements analysis and architecture design
• CI/CD setup and deployment on your server
• REST API documentation and integration description
• Training for portal administrators
• One month of support after release

Infrastructure

The application must be accessible via HTTPS with a valid certificate. For production: dedicated domain, horizontal scaling (tokens in Redis/DB), monitoring of webhook handlers. Log all REST API calls, incoming webhooks, and OAuth exchanges. Proper architecture can save up to 40% on support time.

For more on OAuth, see Wikipedia: OAuth.

Our Bitrix24 integration services cover all types of custom Bitrix24 applications. Whether you need Bitrix24 app development, Bitrix24 marketplace application deployment, or Bitrix24 OAuth setup, we have the expertise. We've built numerous Bitrix24 widgets and Bitrix24 embedded applications that handle millions of records daily. Contact us for a consultation on your project. Get a preliminary timeline and cost estimate.