Bitrix24 Task Widget Installation and Runtime Handler - n8n Workflow

Bitrix24 application developers needing a reliable backend for installation and token management.
Users seeking robust n8n templates for complex webhook interactions.
Automation specialists deploying custom widgets within CRM environments.
Engineers looking for a self-hosted solution for Bitrix24 API handling.

Developing custom applications for platforms like Bitrix24 requires intricate handling of OAuth tokens, installation callbacks, and dynamic content delivery. This powerful n8n workflow solves these challenges by acting as the central handler for all Bitrix24 events related to your custom widget application. The primary value of this n8n template is its ability to seamlessly manage the installation handshake—saving critical access tokens to disk—and then utilizing those stored credentials during runtime to fetch and display context-specific information (like task details) within a Bitrix24 task view tab.

Every time Bitrix24 sends a request (whether for installation or widget display), this specific n8n node setup ensures secure authentication and immediate, tailored responses, showcasing the efficiency of a well-designed n8n workflow.

The entire process begins with the designated n8n trigger, the Webhook node, which listens for POST requests from Bitrix
24.

1. Trigger and Initialization: The Bitrix24 Handler n8n trigger receives the event. The Extract Credentials n8n node immediately parses the incoming JSON payload to retrieve the domain, access tokens, and refresh tokens.


2. Event Determination: The Check Event Type Code node analyzes the request to distinguish between an application installation event (ONAPPINSTALL) and a runtime placement request (e.g., viewing a task).


3. Installation Path: If it is an installation, the workflow branches. If the installation is not yet finished, the system uses the Set Settings Data n8n node to format the tokens, converts them into a JSON file (Create Settings File), and saves the configuration using the Save Installation Settings n8n node (Read/Write File). It then registers the widget placement (Register Placement HTTP Request node) and completes the process with the Installation Response webhook response.


4. Runtime Path (Widget Display): If the event is a runtime request, the system retrieves the previously saved authentication data using the Read Installation Settings and Extract Installation Settings n8n nodes. The Merge request data with installation settings node prepares the necessary data context.


5. Data Processing and Retrieval: The Process Settings Function node extracts context-specific information, such as the taskId. The Has Valid Settings? If node validates the credentials. If valid, the Get Task Data HTTP Request n8n node uses the saved Bitrix24 access token to query the Bitrix24 API for detailed task information.


6. Response Generation: The Format Task Data Function node converts the raw task data into structured HTML. Finally, the Task View Response n8n node sends this HTML back to Bitrix24, which renders it within the custom task widget. If settings were invalid, an Error Response is returned instead. This complex logic demonstrates a powerful application of an n8n workflow.

To deploy this comprehensive n8n workflow, follow these steps:

1. Import the n8n Workflow: Copy the provided JSON data. In your n8n instance, navigate to 'Workflows' and click 'New'. Select 'Import from JSON' and paste the code.


2. Configure the Webhook Trigger: Locate the Bitrix24 Handler n8n trigger node. The Path is set to bitrix24/widgethandler.php. Activate the workflow to generate the full webhook URL. This URL must be registered in your Bitrix24 application settings as the handler URL for installation and placement events.


3. Set Placeholder Credentials: The Extract Credentials n8n node contains hardcoded placeholder values (e.g., local.67b8a796e92127.82791242). These are usually overwritten by the live data from Bitrix24 during the installation webhook, but you might need to adjust them if your application uses different static Client IDs/Secrets. Ensure your Bitrix24 app is configured correctly to send these initial tokens.


4. File System Access: The workflow uses the ReadWriteFile n8n node to save and read the Bitrix24 authentication tokens. Ensure your n8n host environment has the necessary permissions to access the path /data/files/hotline_files/ (or adjust the settingsFilePath variable in the Extract Credentials node to a location accessible by your n8n instance).


5. Activate: Save and activate the n8n workflow. The automation will now listen for Bitrix24 events.

Bitrix24 Handler (Webhook n8n trigger): The entry point of the n8n workflow. It is configured to listen for POST requests at a specific path, initiating the sequence of operations for both installation and task view requests.
Extract Credentials (Set n8n node): Essential for security, this node extracts dynamic authentication parameters (like accesstoken and refreshtoken) sent by Bitrix24, preparing them for use in subsequent HTTP requests and for saving to storage.
Check Event Type (Code n8n node): A custom scripting node that parses the incoming request body to differentiate between app installation callbacks and widget placement events, providing crucial flow control logic for the n8n workflow.
Is Installation? (If n8n node): A core logic n8n node that directs the flow based on whether the current request is part of the application installation process (isInstallation: true).
Set Settings Data & Save Installation Settings (Set & ReadWriteFile n8n nodes): These nodes work together in the n8n template to serialize the newly received Bitrix24 tokens (including expiration and domain) and securely write them to a JSON file on the local filesystem, guaranteeing persistence for later runtime usage.
Register Placement (HTTP Request n8n node): Executes a Bitrix24 API call to bind the custom widget handler URL to the desired placement, specifically TASKVIEWTAB, ensuring the n8n webhook URL is correctly integrated into the Bitrix24 interface.
Read Installation Settings & Process Settings (ReadWriteFile & Function n8n nodes): On runtime access, these nodes retrieve and process the stored tokens, ensuring the n8n workflow has the necessary credentials and context (like the specific taskId) to proceed with API lookups.
Get Task Data (HTTP Request n8n node): Uses the validated access tokens to perform an authenticated call to the Bitrix24 API (tasks.task.get), fetching the details needed for the widget display. This is a critical step in the runtime phase of this n8n workflow.

• Task View Response (RespondToWebhook n8n node): The final action for runtime requests. It packages the HTML generated by the preceding Function node and sends it back immediately to Bitrix24, displaying the custom widget content.