# OIA Shield24: full article text

> OIA Shield24 is a zero-trust API gateway for Bitrix24. It gives vendors, integrators and AI agents scoped, rate-paced, auditable access to your portal REST API through a proxy endpoint, so nobody needs your master webhook or OAuth token.

This file concatenates every article for single-fetch ingestion. Index: https://oia-shield24.infinitybht.app/llms.txt

---
title: "How to Protect and Monitor the Bitrix24 REST API, Step by Step"
description: "Learn how to protect and monitor the Bitrix24 REST API with scoped keys, method allowlists, IP rules, rate limits and request logs, using OIA Shield24."
url: https://oia-shield24.infinitybht.app/blog/bitrix24-rest-api-protection-and-monitoring
published: 2026-10-29
updated: 2026-10-29
author: "OIA Shield24 Team"
category: "REST API Security"
tags: ["rest-api", "security", "monitoring", "observability", "bitrix24"]
site: https://oia-shield24.infinitybht.app
---

# How to Protect and Monitor the Bitrix24 REST API, Step by Step

![Diagram of Bitrix24 REST calls from a vendor, a no-code tool and an AI agent passing through five OIA Shield24 checks before reaching the portal, with blocked requests returning OIA_ERROR codes and everything logged in Observability.](https://oia-shield24.infinitybht.app/blog/img/bitrix24-rest-api-protection-and-monitoring.svg "Every REST call is checked at the edge. Clean requests continue to Bitrix24; blocked ones never reach your portal, and all of them are logged.")

Your Bitrix24 REST API is the back door to your CRM, your tasks, your files and your customers. Anything that holds a working webhook URL can read and change that data, from any network, at any speed, forever, and you will not be told when it does. Most portals hand out that power without a second thought, because the standard way to connect a tool to Bitrix24 is to create an inbound webhook and paste the URL.

This guide shows how to protect the REST API properly and how to watch it afterwards. It uses [OIA Shield24](https://oia-shield24.infinitybht.app/), a Bitrix24 Marketplace app that sits between callers and your portal, but the model applies to any setup: **least privilege, a hard limit on speed, and a record of everything**.

> **Short answer:** Put a gateway between everything that calls your Bitrix24 REST API and the portal itself. Give every caller its own key, allow only the methods it needs, restrict it by IP address, cap its request rate, and read the logs. OIA Shield24 does all five from one screen inside Bitrix24.

## Why the Bitrix24 REST API needs protection

A Bitrix24 inbound webhook is a URL with a secret inside it. It acts with the permissions of the user who created it, for the scopes you ticked when you created it, such as the whole `crm` scope. It does not expire on its own, and nothing in the URL tells you who is using it. That is convenient for a quick integration and risky as soon as the URL leaves your hands.

| Risk | What it looks like | The control that stops it |
|---|---|---|
| Leaked webhook URL | Pasted in a ticket, a chat or a public repository, then used by a stranger | Per-caller keys that can be revoked in one click, plus IP allowlists |
| Over-privileged vendor | An agency that only needed to read deals can also delete them | Method allowlists and read-only operations |
| Runaway script | A loop fires hundreds of calls per second and your portal starts returning limit errors | Per-endpoint rate limits and a request queue |
| Forgotten access | A freelancer finished a year ago and the webhook still works | Expiry dates on every endpoint |
| Unknown activity | Something is hitting the API, but nobody can say what or when | Request logs and threat signals |

## The five layers of protection

OIA Shield24 gives each vendor, tool or agent its own proxy endpoint. Every request to that endpoint passes the same five checks before it can touch Bitrix24:

1. **Identity.** The key or webhook secret must be valid, active and not expired. Keys are hashed for lookup and encrypted at rest, and the Bitrix24 tokens behind them are encrypted too, so the caller never holds a real portal credential.
2. **Method allowlist.** The Bitrix24 method must be on the endpoint's allowed list. A key that may call `crm.deal.list` cannot call `crm.deal.delete`, and some methods that would expose OIA Shield24's own credentials are never available to any vendor.
3. **Network rules.** Optional IP allow and block lists, and an allowed-origins list for browser-based callers, so a leaked key is useless from the wrong network.
4. **Quota and rate.** Your plan's request quota and the endpoint's own requests-per-minute limit are enforced before the call goes out.
5. **Payload checks.** Size limits and a valid JSON shape. Parameters a vendor must never pass, such as access tokens or callback URLs, are refused outright.

Requests that pass are forwarded to Bitrix24 and the answer comes back unchanged, apart from two protections: Bitrix24 file links are swapped for short-lived gateway links, and fields that would reveal credentials are removed from the response. Vendors keep their existing code and swap one base URL for another.

## Step by step: protect your first integration

You will need to be a Bitrix24 administrator for the portal.

1. **Install the app.** Open [OIA Shield24 on the Bitrix24 Marketplace](https://www.bitrix24.com/apps/app/infinitybht_llc.oia_shield24/) and install it, then open it from the left menu.
2. **Open Access Control.** In the app sidebar choose **Access Control**, the Vendor Access Management page. Select **New Vendor**.
3. **Name it and choose the mode.** Give the endpoint a clear name such as `Acme CRM sync`. Pick a vendor type (Developer, Integrator, Agency or External Platform). Choose **API Key** for custom code that can set an `Authorization` header, or **Webhook** for tools that only accept a URL.
4. **Apply least privilege.** Under Allowed Scopes tick only the scopes the integration needs, then switch on only the Allowed Operations required (READ, CREATE, UPDATE, DELETE). The form recommends starting with READ only. For tight control switch on Advanced Method Filtering and list the exact methods. The Templates menu has presets such as listing deals or contacts.
5. **Add network rules and limits.** Set an IP allow list if the caller has fixed addresses (this is a Developer and Enterprise plan feature), choose an expiry from Never, 1 hour, 24 hours, 7 days, 30 days or a custom date, and enter a requests-per-minute limit.
6. **Create the endpoint and copy the credential.** The Endpoint Provisioned dialog shows the key, or the webhook base URL for you to copy. You can reveal it again later with the copy button on the endpoint's row, so keep it in your password manager.
7. **Test it.** Make one allowed call and one that should be refused:

```bash
# Allowed: the endpoint may list deals
curl -s -X POST "https://oia-shield24.infinitybht.app/rest/crm.deal.list" \
  -H "Authorization: Bearer $SHIELD24_ENDPOINT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"select": ["ID", "TITLE"]}'

# Refused: the same key may not delete
curl -s -X POST "https://oia-shield24.infinitybht.app/rest/crm.deal.delete" \
  -H "Authorization: Bearer $SHIELD24_ENDPOINT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": 1}'
```

The second call returns an `OIA_ERROR_INSUFFICIENT_SCOPE` error and never reaches Bitrix24. For a webhook-mode endpoint the URL has the form `https://oia-shield24.infinitybht.app/rest/<alias>/<key>/crm.deal.list`.

## How to monitor the REST API

Protection tells you what is stopped. Monitoring tells you what is happening. Open **Observability** in the app sidebar. The gateway explorer lists requests with their endpoint, status, latency and outcome, and you can filter by any of them. Each endpoint also has a **Logging Compliance** level that decides how much detail is kept: none, metadata only, errors only or full. Metadata only is a sensible default for production, because it records that a call happened without storing customer data.

These are the signals worth acting on:

| Signal in Observability | Usually means | What to do |
|---|---|---|
| Rising `OIA_ERROR_INVALID_CLIENT` | Someone is guessing or replaying a revoked key | Check the source IPs, add an allow list, rotate the key |
| `OIA_ERROR_INSUFFICIENT_SCOPE` from a known vendor | The vendor's code calls a method you never approved | Ask why, then either widen the scope on purpose or fix their code |
| `OIA_ERROR_FORBIDDEN_IP` | A key is being used from outside its allowed network | Treat as a possible leak and rotate |
| `OIA_ERROR_RATE_LIMIT_EXCEEDED` | A script is too fast or stuck in a loop | Fix the caller or raise the limit deliberately |
| One endpoint with a high error rate | A broken integration or a failing upstream | Open the endpoint's requests and read the status codes |

On the Enterprise plan the Threat Intelligence panel does a first pass for you. It reads the last 24 hours of your own traffic and flags IP rule hits, rate-limit abuse, invalid-key attempts, endpoints with high error rates and suspicious IP addresses, each with a plain-language recommendation. It is rule-based, not machine learning, which means its findings are easy to explain to an auditor.

## A 10-minute weekly routine

1. Open Observability and look at the last seven days of errors by code.
2. Investigate any endpoint with invalid-key or forbidden-IP errors.
3. Check which endpoints are close to their expiry date and renew only the ones still needed.
4. Revoke endpoints for vendors you no longer work with.

## Frequently asked questions

### Does a gateway change what Bitrix24 returns?

No. Responses pass through unchanged, except that Bitrix24 file links become short-lived gateway links and credential fields such as access tokens are removed. Vendors do not need to change their parsing code.

### Do my vendors have to rewrite their integration?

No. They replace the base URL and send the new key. The method names, parameters and response shapes stay exactly as in the Bitrix24 REST API.

### Can I protect a no-code tool that only accepts a webhook URL?

Yes. Choose Webhook mode when you create the endpoint. The URL carries an alias instead of your real Bitrix24 member ID, and the same method, IP and rate rules apply.

### What should I do if a key leaks?

Revoke that endpoint from Access Control. Only that one caller loses access and every other integration keeps working. Create a new endpoint with a fresh key and, if you can, add an IP allow list to it.

### Which plan do I need?

Keys, method scoping, rate limits and logs work on every plan, and the Free plan costs nothing. IP allow and block lists need the Developer plan or higher, and the Threat Intelligence panel is on Enterprise. See [pricing](https://oia-shield24.infinitybht.app/#pricing) and the [system limits](https://oia-shield24.infinitybht.app/legal/features) for the current figures.

If your next step is giving a vendor access, read [how to onboard external integrations safely](https://oia-shield24.infinitybht.app/blog/bitrix24-external-integration-safety). If your concern is speed, read [how queue pacing prevents rate-limit errors](https://oia-shield24.infinitybht.app/blog/bitrix24-rate-limit-errors-queue-pacing).

## Next step

**Put this into practice with OIA Shield24** Install OIA Shield24 from the Bitrix24 Marketplace, create your first scoped endpoint in a few minutes, and see every request in Observability. The Starter plan is free.

- [Install on Bitrix24](https://www.bitrix24.com/apps/app/infinitybht_llc.oia_shield24/)
- [Book a meeting](https://oia-shield24.infinitybht.app/#get-started)

---

Published by [OIA Shield24](https://oia-shield24.infinitybht.app). OIA Shield24 is a zero-trust API gateway for Bitrix24. It gives vendors, integrators and AI agents scoped, rate-paced, auditable access to your portal REST API through a proxy endpoint, so nobody needs your master webhook or OAuth token.

Canonical URL: https://oia-shield24.infinitybht.app/blog/bitrix24-rest-api-protection-and-monitoring


---
title: "Bitrix24 External Integration Safety: Onboard Vendors Without Sharing Master Access"
description: "Give agencies, freelancers and SaaS tools access to Bitrix24 without a master webhook. A step-by-step vendor onboarding and offboarding guide with OIA Shield24."
url: https://oia-shield24.infinitybht.app/blog/bitrix24-external-integration-safety
published: 2026-10-29
updated: 2026-10-29
author: "OIA Shield24 Team"
category: "Integration Safety"
tags: ["integrations", "vendors", "least-privilege", "onboarding", "bitrix24"]
site: https://oia-shield24.infinitybht.app
---

# Bitrix24 External Integration Safety: Onboard Vendors Without Sharing Master Access

![Before and after diagram. Before, three vendors share one master Bitrix24 webhook that exposes the whole portal. After, each vendor has its own scoped OIA Shield24 endpoint, one is read-only, one creates leads only, and one has been revoked without affecting the others.](https://oia-shield24.infinitybht.app/blog/img/bitrix24-external-integration-safety.svg "A shared master webhook turns one leak into a portal-wide breach. One scoped endpoint per vendor shrinks the blast radius to a single endpoint.")

Sooner or later someone outside your company asks for access to Bitrix24. A marketing agency wants to push leads in. A developer wants to build a report. A SaaS product wants to sync deals. The usual reply is "create a webhook and send us the URL", and that single message hands over more than most teams realise.

This guide is a practical process for letting vendors work with your portal while keeping control: what to decide before you grant access, how to set it up in OIA Shield24, and how to end it cleanly.

> **Short answer:** Never share one master webhook. Create a separate OIA Shield24 endpoint for each vendor, limited to the methods they need, run as a user with the right permissions, restricted to their IP addresses, and set to expire when the contract does. When the work ends, revoke that endpoint and nothing else is affected.

## The problem with "just send us a webhook"

An inbound Bitrix24 webhook has three properties that make it a poor way to share access:

- **It carries the creator's rights.** If an administrator made it, the vendor now acts as an administrator within the ticked scopes.
- **It is all-or-nothing by scope.** You can choose a scope such as `crm`, but not "list deals only, between 9 and 17, from this server".
- **It is shared and silent.** If the same URL goes to three vendors, you cannot tell their traffic apart, and revoking it breaks all three.

The fix is not to trust vendors less. It is to give each one a credential that can only do their job, can be cut off alone, and leaves a trail.

## The five-question access review

Before you create anything, answer these for every vendor. They map one-to-one to settings in OIA Shield24.

| Question | Setting in the New Vendor form | Effect |
|---|---|---|
| What must they do? | Allowed Scopes, Allowed Operations, Methods Rule | Only listed methods work; everything else is refused |
| Whose permissions should they have? | Run As User | The vendor sees only what that Bitrix24 user can see |
| Where will they call from? | IP allow list, allowed origins | Calls from other networks are refused |
| For how long? | Contract Expiration Date | The key stops working on its own |
| How will you know what they did? | Logging Compliance level | Each request is recorded, with as much detail as you choose |

## Step by step: onboard a vendor

1. **Write a one-paragraph access brief.** Example: "Acme Agency creates leads from web forms. They need `crm.lead.add` only, from two fixed IP addresses, until 31 March."
2. **Open Access Control and select New Vendor.** Name the endpoint after the vendor and the purpose, for example `Acme web forms`. Pick the vendor type that fits: Developer, Integrator, Agency or External Platform.
3. **Choose how they connect.** Pick **API Key** if they write code and can send an `Authorization: Bearer` header. Pick **Webhook** for no-code platforms that only take a URL. A webhook URL uses an alias, so your real Bitrix24 member ID is never revealed to the vendor.
4. **Choose Run As User.** By default the endpoint runs as you. Administrators can pick a different Bitrix24 user, for example a junior sales account, so the vendor can only reach records that account could reach. The user must have opened the app once so their authorization is verified, and if it cannot be confirmed the endpoint is refused instead of quietly using someone else's rights.
5. **Limit the methods.** Tick only the scope the vendor needs and switch on the CREATE operation only. For strict control use Advanced Method Filtering and include exactly `crm.lead.add`.
6. **Add network rules and an expiry.** Enter the vendor's IP addresses in the allow list, add allowed origins if a browser will call the endpoint, and set an expiry. The presets are 1 hour, 24 hours, 7 days and 30 days, or you can choose a custom date.
7. **Set a rate limit and log level.** A modest requests-per-minute limit stops a bug in their code from flooding your portal. Metadata-only logging records what happened without storing customer data.
8. **Send the credential safely and verify.** Copy the key or webhook URL from the Endpoint Provisioned dialog and send it through a password manager, not a chat. Ask the vendor to run one real request, then confirm it in Observability.

A minimal call from the vendor's side looks like this, and it is the only change they make to their code:

```bash
curl -s -X POST "https://oia-shield24.infinitybht.app/rest/crm.lead.add" \
  -H "Authorization: Bearer $VENDOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields": {"TITLE": "Website enquiry", "NAME": "Jane Doe"}}'
```

## Force the values you care about

Some rules are not about permission but about consistency. If every lead from Acme must be assigned to the same manager, you can force it with **Payload Forcing**. Choose the target method, the target payload area and a forced JSON payload:

```json
{ "fields": { "ASSIGNED_BY_ID": 42, "SOURCE_ID": "WEB" } }
```

The forced values are merged into every matching request, overriding what the vendor sent. Because Bitrix24 also accepts changes through GET query strings, an endpoint with forced values refuses GET requests with `OIA_ERROR_METHOD_NOT_ALLOWED`, so a vendor cannot bypass your override.

## Offboarding in one click

The same discipline applies when the work ends.

1. **Let the expiry do the work.** If you set a contract date, the key stops on that day with no action from you.
2. **Disable or revoke early when needed.** On the endpoint's row you can switch it off temporarily or choose **Revoke** and confirm **Revoke Access**. Only that vendor is affected.
3. **Review the log.** Check Observability for the vendor's last activity so you know what they did in the final days.
4. **Rotate on a schedule.** For long-running vendors, issue a new endpoint each year and retire the old one.

## What this does not replace

Scoped endpoints reduce what a vendor can do and make their behaviour visible. They do not replace a contract, and they cannot judge whether a permitted call is sensible. Keep data-protection agreements in place, review what each Bitrix24 user can access, and read the [privacy policy](https://oia-shield24.infinitybht.app/legal/privacy) so you know what OIA Shield24 itself stores.

## Frequently asked questions

### Can a vendor see my real Bitrix24 credentials?

No. The vendor holds an OIA Shield24 key. The Bitrix24 tokens behind it are stored encrypted and are never sent to the vendor, and any token fields in Bitrix24 responses are stripped.

### What if the vendor needs a method I did not allow?

They get an `OIA_ERROR_INSUFFICIENT_SCOPE` response and nothing reaches Bitrix24. You decide whether to widen the endpoint, and the change takes effect immediately.

### Can I give several vendors access at the same time?

Yes, and you should create one endpoint per vendor. Each has its own key, limits, expiry and log trail, and revoking one never affects the others. The number of endpoints you can create depends on your plan.

### Does this work for tools like Zapier or Make?

Yes. Use Webhook mode and the vendor type External Platform. The tool calls a URL, and the same method, rate and IP rules apply.

For the technical side of what each check does, see [how to protect and monitor the Bitrix24 REST API](https://oia-shield24.infinitybht.app/blog/bitrix24-rest-api-protection-and-monitoring). If the next integration is an AI agent, read [how to connect an AI agent to Bitrix24 safely](https://oia-shield24.infinitybht.app/blog/connect-ai-agents-to-bitrix24-safely).

## Next step

**Give your next vendor an endpoint, not the keys** Install OIA Shield24, create a scoped endpoint for the vendor you are onboarding this week, and revoke it the day the contract ends. The Free plan costs nothing.

- [Install on Bitrix24](https://www.bitrix24.com/apps/app/infinitybht_llc.oia_shield24/)
- [Book a meeting](https://oia-shield24.infinitybht.app/#get-started)

---

Published by [OIA Shield24](https://oia-shield24.infinitybht.app). OIA Shield24 is a zero-trust API gateway for Bitrix24. It gives vendors, integrators and AI agents scoped, rate-paced, auditable access to your portal REST API through a proxy endpoint, so nobody needs your master webhook or OAuth token.

Canonical URL: https://oia-shield24.infinitybht.app/blog/bitrix24-external-integration-safety


---
title: "Fix Bitrix24 QUERY_LIMIT_EXCEEDED Errors with Request Queue Pacing"
description: "Stop Bitrix24 REST API rate-limit errors. See why QUERY_LIMIT_EXCEEDED happens and how a per-endpoint queue in OIA Shield24 paces bursts into a steady, safe flow."
url: https://oia-shield24.infinitybht.app/blog/bitrix24-rate-limit-errors-queue-pacing
published: 2026-10-29
updated: 2026-10-29
author: "OIA Shield24 Team"
category: "Performance & Limits"
tags: ["rate-limits", "queue", "performance", "rest-api", "bitrix24"]
site: https://oia-shield24.infinitybht.app
---

# Fix Bitrix24 QUERY_LIMIT_EXCEEDED Errors with Request Queue Pacing

![Diagram showing a burst of Bitrix24 REST calls crossing the limit line on the left, an OIA Shield24 per-endpoint queue in the middle, and evenly spaced requests that stay under the limit on the right, with the 429 and 503 error codes for exceeding the endpoint rate or filling the queue.](https://oia-shield24.infinitybht.app/blog/img/bitrix24-rate-limit-errors-queue-pacing.svg "The queue turns a burst into a steady drip, so Bitrix24 only ever sees traffic it will accept.")

If you have built anything serious on the Bitrix24 REST API, you have met `QUERY_LIMIT_EXCEEDED`. A sync job works for weeks, then a bulk import, a busy morning or a second integration arrives and calls start failing. The usual response is a pile of `sleep` calls and retry loops that make each integration slower and still miss the next burst.

This guide explains why the error happens, why the common fixes fall short, and how to let a per-endpoint queue absorb bursts so Bitrix24 only receives traffic it will accept.

> **Short answer:** Bitrix24 allows only a small, steady number of REST requests per portal, roughly two per second on most plans. Anything faster is rejected with QUERY_LIMIT_EXCEEDED. OIA Shield24 gives each endpoint a queue that releases requests at an even pace set by its requests-per-minute limit, so bursts wait in line instead of failing.

## Why QUERY_LIMIT_EXCEEDED happens

Bitrix24 protects its servers with a request-intensity limit per portal. Think of a bucket with a small hole: requests fill it quickly, it drains slowly, and when it overflows Bitrix24 answers with `QUERY_LIMIT_EXCEEDED` instead of doing the work. The exact allowance depends on your Bitrix24 plan, so check the current figure in the official REST documentation. For most portals the working assumption is about two requests per second.

The limit is shared by everything that calls your portal. One integration may be well behaved, but three of them together, plus your own automation, can overflow the bucket without any of them being at fault. Bursts are the usual trigger:

- A bulk import or nightly sync that fires hundreds of calls at once.
- A webhook that triggers several follow-up calls per event.
- A script that retries immediately on failure, adding even more traffic.
- An AI agent that makes five or six calls in a row to answer one question.

## Why the usual fixes fall short

| Approach | What it does | The catch |
|---|---|---|
| `sleep` between calls | Slows one script | Does nothing for the other callers, and wastes time when the portal is idle |
| Retry on error | Eventually succeeds | Retries add load exactly when the portal is busiest |
| The `batch` method | Combines up to 50 commands in one call | Helps a lot, but only for callers you control, and not for events or third-party tools |
| A message queue you build | Smooths everything | Another system to build, host and monitor |

Batching is still worth using. OIA Shield24 inspects every command inside a batch exactly as if it were a direct call, so a batch cannot be used to smuggle in a method the endpoint does not allow.

## How the OIA Shield24 queue works

Every endpoint gets its own queue, which lives at the edge and handles one request at a time. Here is what happens to each request:

1. **It joins the line.** If the endpoint's queue is already full, the request is turned away at once with HTTP 503 and `OIA_ERROR_PROXY_QUEUE_FULL`, so a surge cannot pile onto your portal.
2. **It waits its turn.** The queue releases one request every `60 / RPM` seconds. A limit of 60 requests per minute means one request per second, and 120 means one every half second.
3. **Dead requests are dropped.** If a caller gives up and closes the connection while waiting, its request is removed and never sent to Bitrix24 (reported as `OIA_ERROR_CLIENT_CLOSED_REQUEST`).
4. **It is sent without blocking the next one.** A slow Bitrix24 reply does not hold up the rest of the line.
5. **The answer comes back with the wait time.** The response carries an `X-OIA-Queue-Time` header giving the milliseconds the request spent waiting.

| Endpoint RPM | Spacing between requests |
|---|---|
| 30 | 2 seconds |
| 60 | 1 second |
| 120 | 500 milliseconds |

The endpoint also keeps a rolling one-minute count. If a caller sends more than the endpoint's requests-per-minute value inside that minute, the extra requests are rejected with HTTP 429 and `OIA_ERROR_RATE_LIMIT_EXCEEDED`, with a `Retry-After` header. The limit you can set depends on your plan.

### Pacing is per endpoint, so budget across them

Each endpoint is paced on its own. Two endpoints each set to 120 requests per minute could together send up to four requests per second. When you issue several endpoints for one portal, choose their limits so the sum stays inside the portal's allowance, and give the busiest integration the largest share.

## Step by step: set up pacing

1. **List your callers.** Write down every integration, tool and agent that calls the portal, and estimate how many requests per minute each needs.
2. **Create one endpoint per caller.** In OIA Shield24 open **Access Control** and choose **New Vendor**, as described in [how to protect and monitor the Bitrix24 REST API](https://oia-shield24.infinitybht.app/blog/bitrix24-rest-api-protection-and-monitoring).
3. **Set the rate limit.** Enter a value in the requests-per-minute field. Start low, such as 60, and keep the total across endpoints within your portal's budget.
4. **Point the caller at the endpoint.** Replace the Bitrix24 base URL with the OIA Shield24 URL and send the new key. Nothing else in the integration changes.
5. **Test with a burst.** Fire ten requests at once and read the queue time on each reply:

```bash
for i in $(seq 1 10); do
  curl -s -o /dev/null -D - -X POST "https://oia-shield24.infinitybht.app/rest/crm.deal.list" \
    -H "Authorization: Bearer $SHIELD24_ENDPOINT_KEY" \
    -H "Content-Type: application/json" \
    -d '{"select": ["ID"]}' | grep -i "x-oia-queue-time" &
done
wait
```

Use a limit of 60 requests per minute for this test, or the highest your plan allows. At 60 the ten values should climb in roughly one-second steps, which shows the burst being spread out. All ten succeed and none of them reaches Bitrix24 faster than the pace you set.

## Make your own code a good citizen

The queue protects the portal, but your code should still handle the two refusals gracefully. Honour `Retry-After` when it is present and back off when the queue is full:

```js
async function callShield24(method, body, attempt = 0) {
  const res = await fetch(`https://oia-shield24.infinitybht.app/rest/${method}`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SHIELD24_ENDPOINT_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });
  if ((res.status === 429 || res.status === 503) && attempt < 5) {
    const waitSeconds = Number(res.headers.get('Retry-After')) || 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));
    return callShield24(method, body, attempt + 1);
  }
  return res.json();
}
```

Set a generous client timeout. A request that waits in the queue is slower than one that does not, by design, and a timeout shorter than the queue wait just turns pacing back into failures.

## Which error is which

| Error | Who raises it | Meaning |
|---|---|---|
| `QUERY_LIMIT_EXCEEDED` | Bitrix24 | The portal itself is overloaded; what pacing is meant to prevent |
| `OIA_ERROR_RATE_LIMIT_EXCEEDED` (429) | OIA Shield24 | This endpoint sent more than its requests-per-minute limit |
| `OIA_ERROR_PROXY_QUEUE_FULL` (503) | OIA Shield24 | Too many requests are already waiting for this endpoint |
| `OIA_ERROR_CLIENT_CLOSED_REQUEST` | OIA Shield24 | The caller disconnected while waiting, so the request was dropped |

## Frequently asked questions

### Does the queue lose requests?

It does not drop a request that is waiting unless the caller disconnects. A request is only refused when the endpoint's queue is full or its per-minute limit is exceeded, and the refusal is explicit, so your code can retry.

### Does pacing make my integration slower?

Individual calls can wait in line, but only as long as needed to keep Bitrix24 under its limit. That is usually faster overall than a failed call plus a retry, and the portal stays responsive for your users.

### Should I still use batch requests?

Yes. Batching reduces the number of requests, and the queue spreads out whatever remains. Both help.

### Can I see how long requests waited?

Yes. Every proxied response includes the `X-OIA-Queue-Time` header, and Observability shows latency per endpoint so you can spot an endpoint whose limit is too low.

Rate limits are one part of a safe integration. For access control, read [how to onboard external integrations safely](https://oia-shield24.infinitybht.app/blog/bitrix24-external-integration-safety), and for a case where pacing matters a great deal, see [how to connect an AI agent to Bitrix24 safely](https://oia-shield24.infinitybht.app/blog/connect-ai-agents-to-bitrix24-safely).

## Next step

**Stop babysitting Bitrix24 rate limits** Install OIA Shield24, set a requests-per-minute value on each endpoint, and let the queue pace your integrations instead of writing retry loops. The Free plan costs nothing.

- [Install on Bitrix24](https://www.bitrix24.com/apps/app/infinitybht_llc.oia_shield24/)
- [Book a meeting](https://oia-shield24.infinitybht.app/#get-started)

---

Published by [OIA Shield24](https://oia-shield24.infinitybht.app). OIA Shield24 is a zero-trust API gateway for Bitrix24. It gives vendors, integrators and AI agents scoped, rate-paced, auditable access to your portal REST API through a proxy endpoint, so nobody needs your master webhook or OAuth token.

Canonical URL: https://oia-shield24.infinitybht.app/blog/bitrix24-rate-limit-errors-queue-pacing


---
title: "Reliable Bitrix24 Outbound Webhooks: Delivery, Retries and Delivery Logs"
description: "Deliver Bitrix24 events to your server without losing them. Set up outbound webhooks in OIA Shield24 with instant acknowledgement, retry backoff and a delivery log."
url: https://oia-shield24.infinitybht.app/blog/bitrix24-outbound-webhooks-reliable-delivery
published: 2026-10-29
updated: 2026-10-29
author: "OIA Shield24 Team"
category: "Events & Webhooks"
tags: ["webhooks", "events", "retries", "reliability", "bitrix24"]
site: https://oia-shield24.infinitybht.app
---

# Reliable Bitrix24 Outbound Webhooks: Delivery, Retries and Delivery Logs

![Diagram of Bitrix24 sending an event to OIA Shield24, which replies 200 immediately and places the event in a durable delivery queue that retries a failing handler with growing delays until it succeeds, with each attempt recorded in a delivery log.](https://oia-shield24.infinitybht.app/blog/img/bitrix24-outbound-webhooks-reliable-delivery.svg "OIA Shield24 acknowledges Bitrix24 at once, then retries delivery to your handler with backoff, up to 14 attempts over about seven hours.")

Bitrix24 can tell your server when something happens: a deal is created, a lead changes stage, a task is completed. It does this by calling a handler URL you provide. The weak point is what happens when your server is slow, restarting or briefly offline. The event arrives, nobody is there to catch it, and it is gone. You find out weeks later when a report does not add up.

This guide shows how to route Bitrix24 events through OIA Shield24 so they are acknowledged instantly, retried automatically, and recorded attempt by attempt.

> **Short answer:** Add your handler under Outbound Events in OIA Shield24 and choose the Robust Queue delivery mode. Bitrix24 gets an immediate 200 reply, and a durable queue in your chosen region calls your handler, retrying failures with growing delays for up to 14 attempts over roughly seven hours. A delivery log shows every attempt.

## Why events get lost

Bitrix24 event handlers are fire-and-forget from Bitrix24's point of view. If your handler is down, returns an error or takes too long, there is no promise that Bitrix24 will try again on your schedule. Three situations cause most losses:

- **Deploys and restarts.** A few seconds of downtime during a release is enough to miss an event.
- **Slow handlers.** If your code does heavy work before replying, the call can time out.
- **Longer outages.** A server or database problem overnight means every event in that window is gone.

Meanwhile the opposite problem also exists. If a handler is flooded after an outage, it may be unable to keep up. A queue gives you a controlled way to deliver and to stop.

## How OIA Shield24 delivers events

Two delivery modes are available on each webhook:

| Mode | How it behaves | Use it when |
|---|---|---|
| **Robust Queue** (recommended) | Bitrix24 is answered with 200 immediately. A durable queue in your chosen region calls your handler and retries failures with exponential backoff | Events matter and your server is not always available |
| **Direct / Real-time** | The event is forwarded straight away, once, with no retries | You want the lowest latency and can tolerate a missed event |

In Robust Queue mode the first retry comes after about 30 seconds, and each following delay grows until it reaches a cap of one hour. A failing handler is called up to 14 times in total, which spans roughly seven hours, long enough to outlive an ordinary overnight outage. If every attempt fails, the rule is switched off with the status `disabled_errors` so it cannot keep hammering a broken server, and you re-enable it once the handler is fixed.

Because retries mean the same event can reach your handler more than once, your handler should be **idempotent**. A simple way is to key your processing on the record ID and event name, so a repeated call changes nothing.

## Step by step: set up a reliable webhook

1. **Prepare the handler.** It must be a public `http://` or `https://` URL that answers with a 2xx status within 10 seconds. Addresses on private networks, loopback addresses and cloud metadata addresses are rejected, which protects against server-side request forgery. Acknowledge first and do the real work afterwards:

```js
import http from 'node:http';

http.createServer((req, res) => {
  let body = '';
  req.on('data', (chunk) => (body += chunk));
  req.on('end', () => {
    res.writeHead(200).end('ok');          // reply fast so the attempt counts as delivered
    queueMicrotask(() => processEvent(body)); // heavy work happens after the reply
  });
}).listen(3000);
```

2. **Open Outbound Events.** In the OIA Shield24 sidebar choose **Outbound Events** and add a new webhook.
3. **Pick the events.** Search the list of Bitrix24 events, or type a custom event name such as `ONCRMDEALADD`.
4. **Enter the handler URL.** Use the address from step 1, for example `https://your-server.com/webhook`.
5. **Choose the delivery mode and region.** Select **Robust Queue**, and set the region under Dynamic Location Hint. The default Auto-Detect is recommended, or lock a region if your data must stay in one jurisdiction.
6. **Send a test delivery.** Use **Send Test Delivery** and confirm your server received it.
7. **Trigger a real event.** Create a deal in Bitrix24 and watch your handler receive the event.
8. **Practise a failure.** Stop your server, create another deal, start the server again, and confirm the event still arrives on a retry.

## Read the delivery log

Open **Observability** and choose the **Outbound Events** tab. The log has one row for every delivery attempt, not every event, so a retried event appears as several rows sharing one delivery ID, with a rising attempt number. Each row ends in one outcome:

| Outcome | What happened |
|---|---|
| `delivered` | Your handler answered with a 2xx status |
| `failed` | Your handler answered, but not with a 2xx status |
| `timeout` | Your handler did not answer within 10 seconds |
| `network_error` | Your handler could not be reached at all |
| `exhausted` | Every retry was used and the event was dropped; the rule is now disabled |
| `queue_full` | The rule's retry backlog reached its limit and the delivery was refused |
| `no_handlers` | The event arrived but no active rule matched it |
| `suspended` | Delivery is paused because the subscription is not active; your rules are kept |

Two details matter for trust. The log stores **metadata only**: timestamp, event name, handler host name, status code, outcome, attempt number, latency and payload size. The payload your handler received and the reply it sent are never written, so no CRM record content ends up in the log. And the delivery log, with its 90-day history, is an Enterprise plan feature. On plans without the log, events are still delivered, but you cannot query the history afterwards.

## When something is wrong

- **Many `failed` rows with the same status code.** Your handler is rejecting the event, for example on an authentication check. Fix it and re-enable the rule if it was disabled.
- **`timeout` rows.** Your handler is doing work before replying. Acknowledge first, then process.
- **`exhausted`.** The outage outlasted the retry window. Fix the handler, re-enable the rule, and reconcile any gap with a REST query for records changed since the outage started.
- **An empty log when you expect events.** A request with an unknown webhook secret or a body over 1 MB is refused before it can be attributed to your portal, so it never appears in anyone's log. Check the secret and payload size first.

## Frequently asked questions

### Does OIA Shield24 store the content of my events?

No. The delivery log records metadata such as the event name, status code and timing, but never the payload or your handler's reply.

### How many times is a failing handler called?

Up to 14 times in Robust Queue mode, starting at about 30 seconds and growing to a one-hour cap, over roughly seven hours. After that the rule is disabled until you re-enable it.

### Can I send events to a server on my private network?

Not directly. Handler URLs must be public. Addresses on private networks, loopback and cloud metadata ranges are blocked on purpose to prevent server-side request forgery. Expose the handler through a public HTTPS address instead.

### Which region processes my events?

The one you choose with Dynamic Location Hint, or an automatically chosen one if you leave it on Auto-Detect. Locking a region keeps processing in that legal jurisdiction.

Events often follow an API integration. To protect the calls going the other way, read [how to protect and monitor the Bitrix24 REST API](https://oia-shield24.infinitybht.app/blog/bitrix24-rest-api-protection-and-monitoring).

## Next step

**Never lose a Bitrix24 event again** Install OIA Shield24, add your handler URL under Outbound Events, and let the delivery queue retry while your server recovers. Every attempt is recorded.

- [Install on Bitrix24](https://www.bitrix24.com/apps/app/infinitybht_llc.oia_shield24/)
- [Book a meeting](https://oia-shield24.infinitybht.app/#get-started)

---

Published by [OIA Shield24](https://oia-shield24.infinitybht.app). OIA Shield24 is a zero-trust API gateway for Bitrix24. It gives vendors, integrators and AI agents scoped, rate-paced, auditable access to your portal REST API through a proxy endpoint, so nobody needs your master webhook or OAuth token.

Canonical URL: https://oia-shield24.infinitybht.app/blog/bitrix24-outbound-webhooks-reliable-delivery


---
title: "How to Connect an AI Agent to Bitrix24 Safely, Without Your Admin Token"
description: "Give ChatGPT-style assistants, MCP tools and custom AI agents controlled access to Bitrix24 with a read-only, rate-paced, expiring endpoint instead of an admin webhook."
url: https://oia-shield24.infinitybht.app/blog/connect-ai-agents-to-bitrix24-safely
published: 2026-10-29
updated: 2026-10-29
author: "OIA Shield24 Team"
category: "AI Agents"
tags: ["ai-agents", "llm", "least-privilege", "rate-limits", "bitrix24"]
site: https://oia-shield24.infinitybht.app
---

# How to Connect an AI Agent to Bitrix24 Safely, Without Your Admin Token

![Diagram of an AI agent calling a dedicated OIA Shield24 endpoint with read-only methods, an IP allowlist, a rate limit, an expiry date and metadata-only logging, before reaching Bitrix24. A delete attempt is refused with OIA_ERROR_INSUFFICIENT_SCOPE and a kill switch revokes the endpoint.](https://oia-shield24.infinitybht.app/blog/img/connect-ai-agents-to-bitrix24-safely.svg "The agent only ever holds a narrow, expiring key. Destructive calls are refused at the edge, and one click revokes the endpoint.")

Customers and teams increasingly ask an AI assistant to answer questions about their CRM: which deals are stuck, who has not been contacted, what changed this week. Making that work means giving the agent a way to call the Bitrix24 REST API. The quick route is to paste an inbound webhook into the agent's configuration. That puts a credential with real write and delete power into a system that follows instructions it finds in text.

This guide shows a safer pattern: a dedicated endpoint for the agent that can read what it needs, at a pace Bitrix24 accepts, for a limited time, and nothing more.

> **Short answer:** Do not give an AI agent your webhook or an administrator token. Create an OIA Shield24 endpoint just for the agent, running as a low-privilege Bitrix24 user, limited to read-only methods, restricted by IP, rate-limited, set to expire, and logged by metadata only. If the agent misbehaves or is tricked, the damage is capped and you can revoke the endpoint in one click.

## Why agents need a different kind of access

An AI agent is not a normal integration. Three things make it riskier and more demanding than a script:

1. **It follows instructions it reads.** Text in a CRM field, an email or a web page can tell an agent to do something the user never intended, a risk usually called prompt injection. You cannot rely on the agent always refusing. What you can rely on is a credential that physically cannot delete records.
2. **It works in bursts.** To answer one question an agent may call the API five or six times in a row. A burst like that can push a portal over its request limit and stall the agent.
3. **It can loop.** A confused agent can repeat a call hundreds of times. Without a rate limit and a log, you find out when the portal slows down.

The solution is to treat the endpoint's permissions as the last line of defence, not the agent's good behaviour.

## What the agent endpoint should look like

| Control | Recommended setting | What it protects against |
|---|---|---|
| Vendor type | External Platform (AI, Zapier) | Applies sensible presets for automation |
| Mode | API Key | The agent sends an `Authorization` header and never sees a URL with a secret inside |
| Run As User | A dedicated Bitrix24 user for the agent | The agent can only see records that user can see |
| Allowed Operations | READ only | Prompt injection cannot delete or edit data |
| Method filtering | `crm.deal.list`, `crm.deal.get`, and similar | The agent cannot reach unrelated parts of the portal |
| IP allow list | The agent's server addresses | A leaked key is useless elsewhere |
| Rate limit | 60 requests per minute to start | Loops and bursts cannot overload the portal |
| Expiry | 30 days | Forgotten agents lose access by themselves |
| Logging | Metadata only | You see what was called without storing CRM content |

## Step by step: connect your agent

1. **Decide what the agent may do.** Write the questions it should answer and the Bitrix24 methods that need. Start with read-only. Writing can come later, as a separate endpoint.
2. **Create a dedicated Bitrix24 user.** Make a user such as "AI assistant" with only the CRM permissions you are happy to expose. Open OIA Shield24 once as that user so the app can verify their authorization.
3. **Create the endpoint.** In OIA Shield24 open **Access Control** and choose **New Vendor**. Name it clearly, for example `Sales assistant (read-only)`. Choose the vendor type External Platform (AI, Zapier) and the mode API Key. The Templates menu includes presets such as listing deals or contacts that you can start from.
4. **Set Run As User.** As an administrator, choose the dedicated user. The agent now inherits that user's permission boundaries on top of the endpoint's own limits.
5. **Restrict the methods.** Switch on the READ operation only, then use Advanced Method Filtering to include just the methods the agent needs.
6. **Add the guardrails.** Add an IP allow list if the agent runs from fixed addresses (a Developer plan feature), set the expiry to 30 days, enter 60 for requests per minute, and choose Metadata only for logging.
7. **Wire the key into the agent's tool.** Store the key as a secret, never in the prompt. A tool function the agent can call looks like this:

```js
export async function listDeals({ stageId, limit = 20 }) {
  const res = await fetch('https://oia-shield24.infinitybht.app/rest/crm.deal.list', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SHIELD24_ENDPOINT_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      filter: { STAGE_ID: stageId },
      select: ['ID', 'TITLE', 'STAGE_ID', 'OPPORTUNITY'],
    }),
  });
  if (!res.ok) throw new Error(`Bitrix24 gateway error ${res.status}`);
  return (await res.json()).result.slice(0, limit);
}
```

   Always pass a `select` list so the agent receives only the fields it needs. This also keeps tokens, and cost, down.

8. **Test the guardrails.** Ask the agent a normal question and confirm it works. Then call a method outside the allowlist yourself, for example `crm.deal.delete`, and confirm it is refused with `OIA_ERROR_INSUFFICIENT_SCOPE`. Finally open **Observability** and check that both calls appear.

## Keep the agent inside Bitrix24's limits

Agents are bursty, which is where the endpoint's queue helps. Requests above the pace you set wait in line instead of failing, and the agent simply receives its answers a little later. If the agent sends more than its per-minute limit, it gets HTTP 429 with a `Retry-After` header, and a well-written tool should wait and try again. The details are in [how queue pacing stops Bitrix24 rate-limit errors](https://oia-shield24.infinitybht.app/blog/bitrix24-rate-limit-errors-queue-pacing).

## Run it safely over time

- **Review the log weekly.** Look for methods the agent calls that you did not expect, rising error counts, and calls at odd hours.
- **Use full logging only briefly.** Switch to full logging while onboarding a new agent so you can debug malformed requests, then go back to metadata only.
- **Renew deliberately.** When the 30 days end, decide whether the agent is still needed instead of extending by default.
- **Add write access separately.** If the agent must create notes or tasks, create a second endpoint that allows only those methods, and force values such as the responsible user with Payload Forcing. See [how to onboard external integrations safely](https://oia-shield24.infinitybht.app/blog/bitrix24-external-integration-safety).
- **Keep the kill switch in mind.** Revoking the endpoint stops that agent immediately and changes nothing else.

## Frequently asked questions

### Does this work with MCP servers and agent frameworks?

Yes, as long as the tool can call the Bitrix24 REST API with a custom base URL and an `Authorization: Bearer` header. Point it at the OIA Shield24 URL instead of your portal. The method names and responses are the same as in the Bitrix24 REST API.

### Can an AI agent still do damage with read-only access?

It can read data you have exposed, so choose the methods and the Run As User with care. It cannot change or delete anything, and the log shows exactly what it read. If some data must never leave Bitrix24, keep it out of the permissions of the agent's user.

### Does OIA Shield24 see my agent's prompts or the CRM data it reads?

The gateway forwards requests to Bitrix24 and does not store request or response bodies at the Metadata only log level. Prompts never reach it, because it only sees the REST calls your agent makes. Read the [privacy policy](https://oia-shield24.infinitybht.app/legal/privacy) for the full details.

### What happens when the agent exceeds its rate limit?

It receives an HTTP 429 response with a `Retry-After` header. Nothing breaks on the Bitrix24 side, and your tool can wait and retry.

### Which plan do I need?

A read-only, rate-limited endpoint with expiry and logging is available on every plan, including the Free plan. IP allow lists need the Developer plan or higher. See [pricing](https://oia-shield24.infinitybht.app/#pricing).

## Next step

**Let your AI agent use Bitrix24 without the risk** Install OIA Shield24, create a read-only endpoint for your agent in minutes, and see every call it makes in Observability. The Free plan costs nothing.

- [Install on Bitrix24](https://www.bitrix24.com/apps/app/infinitybht_llc.oia_shield24/)
- [Book a meeting](https://oia-shield24.infinitybht.app/#get-started)

---

Published by [OIA Shield24](https://oia-shield24.infinitybht.app). OIA Shield24 is a zero-trust API gateway for Bitrix24. It gives vendors, integrators and AI agents scoped, rate-paced, auditable access to your portal REST API through a proxy endpoint, so nobody needs your master webhook or OAuth token.

Canonical URL: https://oia-shield24.infinitybht.app/blog/connect-ai-agents-to-bitrix24-safely