Setting up the Bitrix24 integration with Notion

Setting up Bitrix24 Integration with Notion

Documentation lives in Notion, deals and tasks live in Bitrix24. A manager closes a deal, then manually goes to Notion to update the project table. A developer fixes requirements in the Notion database, then duplicates them as a task in B24. A month later, the two systems show different data, and nobody knows which version is current. Manual copying between B24 and Notion guarantees data desynchronization.

Integration Architecture

The integration works through Notion API v1 and B24 REST API. Notion provides API for working with databases, pages, and blocks. B24 provides webhooks for subscribing to CRM, task, and business process events. A middleware server sits between them, listening to events from both sides and translating data.

B24 (CRM/task event) → Webhook → Middleware → Notion API → Database/Page
Notion (polling/webhook) → Middleware → B24 REST API → CRM/tasks

Notion API does not yet support native webhooks for tracking changes. The middleware uses polling — querying the Notion database with a last_edited_time filter every 30–60 seconds. B24 uses standard webhooks via event.bind.

Syncing Notion Databases with CRM

The main scenario is mirroring CRM records into a Notion database. Set up field mapping:

When a deal's stage changes in B24 (event ONCRMDEALUPDATE), the middleware updates the corresponding record in Notion via PATCH /v1/pages/{page_id} with the new select property value. In reverse — when a status changes in Notion, the middleware calls crm.deal.update.

Creating Pages from CRM Events

When a B24 event occurs, the middleware automatically creates a page in Notion with populated content:

• New deal → page in the "Projects" database with client details, amount, responsible person. Page body contains a template: sections for "Requirements," "Deadlines," "Contacts."
• Won deal → page in the "Active Projects" database with automatic transfer of data from the deal card.
• New task → record in a Kanban-style Notion database linked to the project.

Creating a page is a POST /v1/pages call with parent.database_id and a properties array. Page content is passed as a block array: paragraph, heading_2, to_do, table.

Bidirectional Updates

The middleware maintains a mapping table: b24_entity_id ↔ notion_page_id. On each update, the source is checked to prevent loops:

1. B24 updates a deal → middleware writes sync_source = "b24" to metadata.
2. Middleware updates the Notion page.
3. On the next poll, the middleware sees the change, but checks the timestamp — if the update occurred within 10 seconds of the middleware write, it is skipped.

For text fields, use last write wins strategy — the most recent change wins. For statuses, use configurable priority (you can specify which system is master).

Notion API Limitations

Notion API has rate limits — 3 requests per second per integration. The middleware queues requests and maintains intervals. On receiving 429 Too Many Requests — exponential backoff.

Payload size is limited: maximum 100 blocks per page creation request. For larger documents, the middleware splits content across multiple PATCH /v1/blocks/{block_id}/children calls.

Authentication and Access

• Notion: Internal Integration Token. Created in Settings → Integrations. The integration must be manually connected to each database via "Add connections" — without this, the API cannot see the database.
• B24: OAuth 2.0 with scope crm,task,user. Refresh token updates automatically.
• The middleware stores both tokens encrypted. Data flows only through your server.

What We Implement

• Middleware for bidirectional B24 CRM and Notion database synchronization
• Automatic Notion page creation from CRM events
• Field mapping from CRM to Notion Database properties
• Bidirectional status updates with loop protection
• Request queue with Notion API rate limit handling
• Polling mechanism for tracking Notion changes