> For the complete documentation index, see [llms.txt](https://docs.tumbler.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tumbler.app/ru/funkcii/acc-callbacks.md).

# \[PAID] ACC callbacks: события и доставка

## Для кого

Провайдеры, которые включают Advanced Connection Control и хотят получать события о превышении лимитов.

## Что можно сделать

* Настроить callback endpoint через metadata.
* Проверять подпись каждого события.
* Обрабатывать soft/hard события идемпотентно и с учётом ретраев.

## Примеры

* `acc.limit.soft_reached` — лимит достигнут, соединение разрешено.
* `acc.limit.hard_denied` — лимит достигнут, соединение отклонено.
* `X-Callback-Signature` — HMAC-подпись тела события.

## См. также

* [advanced-connection-control.md](/ru/funkcii/advanced-connection-control.md)
* [features/overview.md](/ru/funkcii/overview.md)
* [security/fetcher-restrictions.md](/ru/uluchsheniya-posle-pervogo-zapuska/fetcher-restrictions.md)

## Конфигурация

Callback включается metadata-полями подписки или ноды:

* `acc-callback-url: https://...` - адрес приема событий; только HTTPS.
* `acc-callback-secret: <string>` - общий секрет для подписи; храните и ротируйте как credential.
* `acc-callback-events: limit_soft,limit_hard` - опциональный список через запятую.

Если `acc-callback-events` не задан, отправляются все события ACC.

Маппинг значений:

| Значение в `acc-callback-events` | Тип события              |
| -------------------------------- | ------------------------ |
| `limit_soft`                     | `acc.limit.soft_reached` |
| `limit_hard`                     | `acc.limit.hard_denied`  |

## Когда вызывается

* При попытке соединения, которая превышает `acc-connection-limit` в выбранной области: `subscription`, `config` или `group`.
* В `soft` режиме событие фиксирует превышение, но соединение допускается.
* В `hard` режиме событие сопровождается отказом в подключении.

Callbacks отправляются только если ACC активирован. Если ACC выключен или capability не разрешена тарифом, callback-поля игнорируются.

## Безопасность и подпись

* Принимаются только HTTPS URL.
* URL должен соответствовать ограничениям outbound/fetcher безопасности; не используйте localhost, private IP, нестандартные схемы и userinfo.
* Каждый `POST` содержит заголовки:
  * `X-Callback-Timestamp-Ms` - Unix time в миллисекундах, когда сформирована подпись.
  * `X-Callback-Id` - UUID события; один и тот же для всех повторных попыток доставки.
  * `X-Callback-Signature` - `base64( HMAC-SHA256(secret, timestamp + "\n" + sha256(body)) )`, где:
    * `timestamp` - строка из `X-Callback-Timestamp-Ms`;
    * `sha256(body)` - hex-строка SHA-256 от необработанного JSON-тела.

Провайдер должен сверить подпись и свежесть timestamp. Возвращайте `2xx` только после успешной проверки и обработки.

## Идемпотентность

`X-Callback-Id` уникален для логического события и не меняется при ретраях. Endpoint должен дедуплицировать повторы с тем же ID и безопасно возвращать тот же результат.

## Типы событий

* `acc.limit.soft_reached` - лимит достигнут, режим `soft`, соединение разрешено.
* `acc.limit.hard_denied` - лимит достигнут, режим `hard`, соединение отклонено.

## Тело события

Минимальный набор полей:

* `event_type` - тип события.
* `occurred_at_ms` - Unix time в миллисекундах, когда событие зафиксировано.
* `provider_domain` - домен провайдера.
* `subscription_id` - идентификатор подписки.
* `scope` - `subscription`, `config` или `group`.
* `group` / `cid` - включаются, если применимо для области.
* `installation_id` - псевдонимный UUID установки.
* `device_type` - тип устройства, как его прислал клиент.
* `active_connections` - текущее количество активных соединений после события.
* `limit` - настроенный порог для выбранной области.
* `node_id` - узел, если известен.
* `reason` - код причины, например `connection_limit_exceeded`.

Пример:

```json
{
  "event_type": "acc.limit.hard_denied",
  "occurred_at_ms": 1700000000123,
  "provider_domain": "example.com",
  "subscription_id": "sub_123",
  "scope": "group",
  "group": "eu",
  "cid": "stable-config-id",
  "installation_id": "1c1fc3a9-2f7e-4db8-9c15-9e8b6f5c1d00",
  "device_type": "ios",
  "active_connections": 3,
  "limit": 2,
  "node_id": "edge-eu-1",
  "reason": "connection_limit_exceeded"
}
```

## Идентификаторы области

* VLESS: `group` и `cid` берутся из query `group=<...>` и `cid=<...>` и попадают в `node.meta`.
* JSON: `meta.group` и `meta.cid` передаются в область события.

## Политика доставки

* Доставка `at-least-once`.
* Один и тот же `X-Callback-Id` переиспользуется при повторах.
* Повторы выполняются при сетевых таймаутах, `5xx` или `429`.
* Максимум 10 попыток в течение 24 часов.
* Backoff экспоненциальный: секунды, затем минуты, с cap около 30 минут между попытками.
* После исчерпания попыток или истечения 24 часов событие помечается dead; дальнейших ретраев нет.

## Ожидания к ответу

* `2xx` - принято, дальнейших ретраев нет.
* `4xx`, кроме `429` - постоянная ошибка; событие помечается dead без повторов.
* `429` или `5xx` - временная ошибка; будет повторная попытка.
* Ответ должен быть быстрым и не требовать session cookies.

## Совместимость

* Игнорируйте неизвестные поля для forward compatibility.
* Новые поля могут добавляться без изменения существующих ключей.
* Не меняйте семантику `X-Callback-Id`: это ключ идемпотентности.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tumbler.app/ru/funkcii/acc-callbacks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.