Bitrix24 On-Premise: Fix Webhooks in Business Processes

In Bitrix24 on-premise setups, incoming webhooks like im.message.add.json triggered from business processes often stop working because agents execute “on hit” rather than via cron, leading to delays where the BP finishes before the webhook processes. This creates a race condition—no errors show, but messages never hit the chat since the HTTP request ends too soon. Switch to cron-based agent execution for reliable delivery, and check workflow delays or security filters as quick fixes.

Contents

• Why Bitrix24 Webhooks Fail in Business Processes
• The Agent Execution Problem in On-Premise
• Setting Up Cron for Reliable Webhooks
• Troubleshooting Business Process Webhooks
• im.message.add.json Specific Issues
• Known Limitations and Next Steps

Why Bitrix24 Webhooks Fail in Business Processes

Picture this: your business process kicks off perfectly, hits that incoming webhook URL—say, https://site/rest/user/code/im.message.add.json?DIALOG_ID=chat&MESSAGE=text—and logs no errors. Yet the chat stays silent. Frustrating, right? In Bitrix24 on-premise, this “works in browser but not from BP” pattern screams timing issues.

The root? Agents handling REST API calls like im.message.add.json run asynchronously after the BP’s main thread wraps up. If it’s “on hit” mode (default for many self-hosted installs), webhooks queue up but don’t fire until the next page load. Since December 1, 2025, any license or update quirks might exacerbate this, but the core fix isn’t a new code—it’s rethinking execution.

You’ve already tested direct calls (smart move) and regenerated tokens. Good. But when BPs invoke webhooks internally, they bypass some checks, hitting permission walls or filters silently.

The Agent Execution Problem in On-Premise

Bitrix24’s agents—those background tasks powering webhooks and REST API hits—default to “on hit” in on-premise. Meaning? They only process when someone loads a portal page. Your BP triggers the webhook, but without a hit, im.message.add.json sits in limbo.

Why now, post-December 1? Updates or license renewals can tweak agent priorities, but Bitrix24’s official docs on agent cron nail it: on-premise needs cron for production reliability. Webhooks from BPs especially suffer because the process thinks it’s done, releasing the request before agents run.

Agents like the one for im.message.add.json need CEvent::ProcessEventQueue(); to flush. On hit? Sporadic. Cron? Predictable every 5 minutes.

Setting Up Cron for Reliable Webhooks

Ready to fix it? Ditch “on hit” for cron—it’s the gold standard for Bitrix24 business processes using webhooks.

First, disable on-hit agents. SSH into your server and run:

php -f /path/to/bitrix/php_interface/dbconn.php
COption::SetOptionString("main", "agents_use_crontab", "Y");
COption::SetOptionString("main", "check_agents", "N");

Mark key agents as “periodical” in Settings > Tools > Agents. Then set up the cron job:

*/5 * * * * /usr/bin/php -f /home/bitrix/www/bitrix/php_interface/cron_events.php

Your cron_events.php must include:

<?php
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");
CAgent::RunAgents();
CEvent::ProcessEventQueue();
?>

Boom—webhooks process immediately, no more BP ghosts. Detailed cron guide here confirms this resolves 90% of “webhook not working” tickets.

Test: Trigger your BP, wait 5 mins, check chat. Messages flow.

Troubleshooting Business Process Webhooks

Beyond cron, dig deeper. Bitrix24’s workflow troubleshooting lists killers:

• Conditions fire too early: Webhook creates items, but BP rules check fields not yet populated. Fix: Add a 10-minute delay action before the webhook.
• Security filters: Special chars in payloads or URLs block silently. Check BP logs for “security filter” errors.
• Permissions: BP runs as the “initiator” or system user? Ensure they have chat send rights. Test with admin.
• DIALOG_ID woes: Must be numeric chat ID, not string. Verify via REST im.chat.get.

BP runs clean? Enable debug: Settings > Business Processes > Logs. Hunt for webhook HTTP responses.

Regen webhook? Useless if agents lag.

im.message.add.json Specific Issues

Your endpoint—im.message.add.json—pushes to chats via REST. Works standalone? Great. From BP? Often not, due to context.

Key gotchas:

• JSON payload strictness: BP passes GET params? Fine, but ensure DIALOG_ID={=Document:CHAT_ID} resolves numerically.
• Event queue: Ties back to agents. Cron flushes it.
• Rate limits: On-premise rarely hits, but post-update (Dec 2025), check license quotas.

Example fix in BP: Use “REST API Call” activity with full JSON body:

{
 "DIALOG_ID": "{=Document:CHAT_ID}",
 "MESSAGE": "Your text here"
}

Still nada? Tail logs: /bitrix/modules/main/admin/agent_list.php shows execution times.

Known Limitations and Next Steps

Bitrix24 isn’t flawless. Community reports, like this dev blog, note official confirmation: some BP-triggered webhooks “will not work” due to open tickets. Your case matches—REST from internal BP.

Next:

1. Implement cron (priority).
2. Delay in BP.
3. Audit permissions/logs.
4. If stuck, Bitrix24 support ticket with agent logs.

On-premise shines with cron. Post-fix, your business processes will hum.

Sources

1. Troubleshooting workflows and automation rules
2. Execution of all agents via Cron
3. Launching of Agents from Cron
4. Расширение возможностей бизнес-процессов с помощью вебхуков

Conclusion

Switching Bitrix24 on-premise agents to cron fixes most webhook failures in business processes, ensuring im.message.add.json delivers reliably—no more silent drops. Combine with BP delays and log checks for bulletproof automation. You’ll wonder why it wasn’t cron from day one. If issues linger post-Dec 2025 updates, it’s likely a known BP limitation—escalate with logs.