Skip to content

BITRIX24_LOCAL_INTEGRATION.md

Latest commit

 

History

History
240 lines (174 loc) · 10.2 KB

BITRIX24_LOCAL_INTEGRATION.md

File metadata and controls

240 lines (174 loc) · 10.2 KB
Raw

Bitrix24 Local Integration

This document explains where to get the secret Bitrix24 incoming webhook, why it is needed and where to paste it during Pinguva setup.

What You Enter In The Pinguva UI

In the Pinguva UI, enter only the public Bitrix24 portal address:

b24.example.kz

Pinguva uses it to generate a command for the Bitrix24 server. The webhook secret is not entered into the Pinguva UI.

The integration uses the same Pinguva Linux agent that is already installed on the Bitrix24 server. It does not install a separate Bitrix24 agent. For local load diagnostics, the setup command enables a short system timer that produces only a redacted technical summary and sends it through the existing agent authorization. The primary server telemetry remains separate.

What You Enter In The Terminal

After running the generated command, the agent asks:

Bitrix24 webhook URL / Входящий webhook Bitrix24 (hidden input, not the portal URL):

Paste the incoming webhook created inside Bitrix24. This is a secret. Input is hidden, the value is not printed on the screen and it is stored only locally on the customer server.

How To Create An Incoming Webhook In Bitrix24

  1. Sign in to Bitrix24 as a user that can safely run REST checks.
  2. Prefer a dedicated technical user with minimal permissions, not a personal administrator account.
  3. Open Applications in Bitrix24.
  4. Open Developers.
  5. Open Ready-made scenarios.
  6. Choose Other.
  7. Choose Incoming webhook.
  8. Set a clear name, for example Pinguva REST monitoring.
  9. Grant only the permissions required by the selected Pinguva REST profiles.
  10. Save the webhook.
  11. Copy the URL from the request generator.

The official Bitrix24 documentation describes this path as Applications > Developers > Ready-made scenarios > Other > Incoming webhook.

Which Permissions To Choose

For the standard profile set, grant the incoming webhook:

  • Users: brief data (user_brief) for the user.current availability check, the scope granted-permissions check and the optional user.get check;
  • CRM when crm_deals, crm_leads, crm_contacts or crm_statuses are selected.

scope is not a separate Bitrix24 permission. This profile only checks the REST permissions already granted to the webhook.

For the dedicated technical user, grant read-only access to deals, leads and contacts. Do not use a personal administrator account and do not grant more permissions than the selected profiles need. If CRM profiles are not selected, do not grant CRM access.

The method_discovery profile is disabled by default. When enabled manually, it checks availability of user.get through method.get.

What Exactly To Copy

A Bitrix24 webhook URL usually looks like this:

https://b24.example.kz/rest/1/secret_code/profile/

or as a full method call example:

https://b24.example.kz/rest/1/secret_code/user.current.json

You can paste the full request-generator URL into Pinguva agent setup. The agent uses only the base webhook part:

https://b24.example.kz/rest/1/secret_code

Do not put this URL into the Pinguva UI, command history, support tickets or logs.

Where To Paste The Webhook

Run the short command generated by the Bitrix24 card in Pinguva:

curl -fsSL "https://monit.pinguva.com/install/bitrix24.sh" | sudo bash -s -- --base-url "https://b24.example.kz"

The command updates the existing Pinguva Linux agent, starts local Bitrix24 setup, enables a one-minute local diagnostics timer and restarts the same pinguva-agent service after saving the config. After it starts, the hidden input prompt appears:

Bitrix24 webhook URL / Входящий webhook Bitrix24 (hidden input, not the portal URL):

Paste the webhook and press Enter. Characters are not displayed. This is expected.

Where The Secret Is Stored

The webhook is stored only on the customer server:

/etc/pinguva-agent/bitrix24.json

The file is created with restricted permissions. Pinguva receives only a technical check summary: status, latency, selected REST method, safe count and a short error after secret redaction.

Local Load Diagnostics

Starting with agent version 0.2.12, the setup command also enables pinguva-bitrix24-diagnostics.timer. Every minute it reads only a bounded recent window of standard Nginx/Apache access logs and MySQL technical status on the customer host. This identifies routes that contribute to load without sending logs or CRM data to Pinguva. Extra collection starts only after the Pinguva server confirms the feature for the workspace; the agent accepts no diagnostic commands or parameters from the server.

Pinguva can show:

  • dynamic request and 5xx counts in the last 15 minutes;
  • the most active normalized paths, such as /api/accruedpoints;
  • traffic sources with the final IP segment masked;
  • Threads_running, active query count and longest current MySQL query;
  • fixed technical query categories, for example a case-insensitive CRM contact lookup.

The extended Bitrix24 Load Diagnostics section provides periods up to 24 hours, separate REST, 5xx and MySQL series, load incidents, heavy SQL groups and routes that overlap with them in time. This is correlation, not proof that a particular route caused a particular SQL statement.

Regular history uses minute aggregates. During an incident, the same root timer collects at most two extra MySQL samples at a 10-second interval and stops within 20 seconds. It is for spike investigation, not per-request tracing. Its local buffer of unsent events is closed to other users (root:root, 0700 directory, 0600 files) and is limited to 24 hours or 100 MiB.

Starting with agent version 0.2.12, the task first uses /root/.my.cnf only when it is a regular root:root file with strict 0600 permissions. This is a common self-hosted Bitrix24 setup: the password stays on the server and never appears in command arguments, logs or Pinguva. The agent does not change an unsafe file and uses the standard local MySQL socket instead.

For MySQL and MariaDB, the agent tries performance_schema.global_status first, then SHOW GLOBAL STATUS, and finally information_schema.GLOBAL_STATUS. Thread status and the active query list are collected separately: 0 active queries and 0 seconds maximum duration are a healthy quiet snapshot, not an error. A global ALL PRIVILEGES ON *.* grant includes PROCESS; the agent recognizes it when validating current-query access. When grants are unavailable or do not list the privilege, a successful PROCESSLIST query remains healthy: no foreign sessions at that instant is not an error.

If access logs or MySQL are unavailable to the local task, Bitrix24 REST checks continue. The server card shows the unavailable local summary separately.

Updating An Existing Bitrix24 Integration

An already configured Bitrix24 integration does not need a new webhook or a repeat setup. Its server card in Pinguva shows that Bitrix24 diagnostics are available. Copy and run the normal agent-update command.

Starting with version 0.2.12, it performs additive actions only:

  • updates the agent binary;
  • only when /etc/pinguva-agent/bitrix24.json already exists, enables local diagnostics and pinguva-bitrix24-diagnostics.timer;
  • does not change the webhook, REST profiles or a custom access-log path;
  • starts the first local snapshot.

Within one to two minutes, the card shows route, 5xx, source and MySQL aggregates plus period history. Up to ten discovered important routes can be selected in the diagnostics section. Pinguva stores normalized paths only; the agent receives them in the response to its own outbound report. This creates no additional REST calls and does not alter Bitrix24 settings.

If the access log is outside a standard system path, rerun the setup command with its local path. Neither the path nor log contents are sent to Pinguva:

curl -fsSL "https://monit.pinguva.com/install/bitrix24.sh" | sudo bash -s -- \
  --base-url "https://b24.example.kz" \
  --access-log "/srv/bitrix/logs/nginx-access.log"

What Is Not Sent To Pinguva

Pinguva does not receive:

  • Bitrix24 incoming webhook;
  • request or response bodies;
  • CRM records;
  • deal names;
  • phone numbers;
  • emails;
  • comments;
  • custom fields;
  • files or attachments.
  • raw access-log lines;
  • URL parameters, cookies or authorization headers;
  • source SQL or SQL values. When the agent can safely remove values, it may send only a redacted SELECT structure; otherwise it sends only digest, category and technical counters.

Check After Setup

sudo pinguva-agent bitrix24 status
sudo journalctl -u pinguva-agent -n 50 --no-pager
sudo systemctl status pinguva-bitrix24-diagnostics.timer --no-pager
sudo journalctl -u pinguva-bitrix24-diagnostics.service -n 50 --no-pager

To confirm that metrics are sent without revealing the password:

sudo stat -c '%a %U:%G %F' /root/.my.cnf
sudo systemctl start pinguva-bitrix24-diagnostics.service
sudo journalctl -u pinguva-bitrix24-diagnostics.service -n 50 --no-pager | grep 'Bitrix24 MySQL diagnostics'

The expected file mode is 600 root root regular file. A successful journal line contains connection=defaults_extra_file, a status source, processlist_status=ok, query_groups_status=ok and status=ok. process_privilege_source=functional_check is also healthy when the diagnostic queries themselves completed successfully. The root-only timer sends historical aggregates within one or two minutes. Never print /root/.my.cnf contents in logs or support requests.

If the bitrix24 command is unknown, update the agent to version 0.2.12 or newer.

If The Webhook Owner Changes

REST calls through an incoming webhook run with the permissions of the user who created it. If that user is disabled, deleted or loses permissions, the Bitrix24 check may stop working. Create a new webhook and re-run agent setup.

Official Bitrix24 Materials