Разное

Мониторинг вебхуков

Описание метода

Метод возвращает агрегированную статистику по вызовам выбранных вебхуков за последние 60 минут: всего вызовов, успешных, с ошибками, число повторных попыток, доля ошибок. Метод предназначен для постоянного автоматического контроля исходящих интеграций: отправки данных в кассы, чат-центры, на склады, в маркетплейсы и собственные сервисы заказчика.

По возвращаемым данным можно настроить дашборды и алерты — например, «доля ошибок при отправке в курьерскую службу больше 5% за последние 60 минут» или «нет ни одного вызова кассы за последние 60 минут». Это позволяет узнать о проблеме раньше, чем ее заметят бизнес-пользователи или клиенты.

Для детального разбора инцидента используйте Логи вызовов вебхуков или их выгрузку — там есть тела запроса и ответа, тексты ошибок, идентификаторы транзакций, номера попыток и точное время запроса. Метод мониторинга не отдает детализацию по отдельным попыткам.

Если статистика нужна только в интерфейсе Mindbox — используйте раздел Мониторинг интеграций.

Предварительная настройка

Создайте операцию мониторинга в разделе Кампании → Операции (как создать операцию V3) со следующими параметрами:

Системное имя — произвольное, используется в URL запроса;
Для точек интеграции — точка, на которой будет работать метод, используется в URL запроса;
Шаг — Мониторинг → Статистика по вебхукам.

Формат запроса

Подробнее о работе с V3 API, URL запросов и заголовках: Документация V3 API.

URL и параметры

POST на адрес:

Code

https://api.mindbox.ru/v3/operations/sync?endpointId={Идентификатор точки интеграции}&operation={Системное имя операции мониторинга}

Заголовки

Заголовок	JSON	XML	Обязательное
Content-Type	`application/json; charset=utf-8`	`application/xml; charset=utf-8`	✅
Accept	`application/json`	`application/xml`	✅
Authorization	`SecretKey {секретный_ключ_точки_интеграции}`		✅

Тело запроса

{
  "webhooks": [
    {
      "webhookId": "<UUID вебхука>",
      "integrationId": "<UUID интеграции>"
    },
    {
      "webhookId": "<UUID вебхука>",
      "integrationId": "<UUID интеграции>"
    }
  ]
}

Идентификаторы передаются как UUID из адресной строки со страницы интеграции или вебхука на проекте Mindbox. Системные имена в этом методе не принимаются и возвращают notFound.

Если у вас нет доступа к проекту, запросите корректные UUID у владельца или менеджера проекта.

monitoring-webhook-api

В массив webhooks можно передать несколько фильтров: статистика возвращается отдельно для каждого. Фильтры комбинируются:

Содержимое элемента	Что вернется
`webhookId` + `integrationId`	Статистика по конкретной паре. Оба идентификатора должны совпадать с привязкой интеграции и вебхука на проекте, иначе вернется `notFound`
`webhookId`	Статистика по вебхуку. `integrationId` и `integrationName` подтягиваются автоматически
`integrationId`	Список вебхуков этой интеграции, у которых был хотя бы один вызов за последние 60 минут
Пустой массив `"webhooks":[]` или пустой запрос	Статистика по всем вебхукам проекта
Массив с пустым объектом `"webhooks":[{}]`	Ошибка валидации

Пример запроса

Статистика по одному вебхуку

POST https://api.mindbox.ru/v3/operations/sync?endpointId=demo.Website&operation=MonitoringWebhooks

Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: SecretKey {секретный_ключ_точки_интеграции}

{
  "webhooks": [
    {
      "webhookId": "8f3a1b2c-1111-2222-3333-444455556666",
      "integrationId": "1a2b3c4d-aaaa-bbbb-cccc-ddddeeeeffff"
    }
  ]
}

Несколько вебхуков в одном запросе

В ответе — три записи, по одной на каждый вебхук. Порядок записей в ответе совпадает с порядком в запросе.

POST https://api.mindbox.ru/v3/operations/sync?endpointId=demo.Website&operation=MonitoringWebhooks

Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: SecretKey {секретный_ключ_точки_интеграции}

{
  "webhooks": [
    {
      "webhookId": "8f3a1b2c-1111-2222-3333-444455556666",
      "integrationId": "1a2b3c4d-aaaa-bbbb-cccc-ddddeeeeffff"
    },
    {
      "webhookId": "9e4b2c3d-2222-3333-4444-555566667777",
      "integrationId": "1a2b3c4d-aaaa-bbbb-cccc-ddddeeeeffff"
    },
    {
      "webhookId": "af5c3d4e-3333-4444-5555-666677778888",
      "integrationId": "2b3c4d5e-bbbb-cccc-dddd-eeeeffff0000"
    }
  ]
}

Все вебхуки одной интеграции

В ответе — все вебхуки этой интеграции, у которых были вызовы за последние 60 минут.

POST https://api.mindbox.ru/v3/operations/sync?endpointId=demo.Website&operation=MonitoringWebhooks

Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: SecretKey {секретный_ключ_точки_интеграции}

{
  "webhooks": [
    { "integrationId": "1a2b3c4d-aaaa-bbbb-cccc-ddddeeeeffff" }
  ]
}

Вебхук с автоматическим получением интеграции

Метод сам найдет привязку вебхука к интеграции и вернет integrationId и integrationName в ответе.

POST https://api.mindbox.ru/v3/operations/sync?endpointId=demo.Website&operation=MonitoringWebhooks

Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: SecretKey {секретный_ключ_точки_интеграции}

{
  "webhooks": [
    { "webhookId": "8f3a1b2c-1111-2222-3333-444455556666" }
  ]
}

Поиск опечаток в фильтре

Во втором и третьем элементе есть опечатки в UUID. В ответе для этих элементов будет status: "notFound" — это помогает находить опечатки на этапе настройки дашборда.

POST https://api.mindbox.ru/v3/operations/sync?endpointId=demo.Website&operation=MonitoringWebhooks

Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: SecretKey {секретный_ключ_точки_интеграции}

{
  "webhooks": [
    {
      "webhookId": "8f3a1b2c-1111-2222-3333-444455556666",
      "integrationId": "1a2b3c4d-aaaa-bbbb-cccc-ddddeeeeffff"
    },
    {
      "webhookId": "00000000-0000-0000-0000-000000000000",
      "integrationId": "1a2b3c4d-aaaa-bbbb-cccc-ddddeeeeffff"
    },
    {
      "webhookId": "8f3a1b2c-1111-2222-3333-444455556666",
      "integrationId": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

Ответ

Пример успешного ответа

{
  "status": "Success",
  "webhookStatistics": [
    {
      "webhookId": "8f3a1b2c-1111-2222-3333-444455556666",
      "webhookName": "Передача заказа в доставку",
      "integrationId": "1a2b3c4d-aaaa-bbbb-cccc-ddddeeeeffff",
      "integrationName": "Сервис доставки",
      "totalCalls": 142,
      "successCalls": 138,
      "failedCalls": 4,
      "totalRetries": 6,
      "errorRate": 2.82,
      "status": "hasData"
    }
  ]
}

Описание параметров ответа

Поле	Описание
`status`	Результат обработки запроса в целом
`webhookStatistics[].webhookId`	UUID вебхука
`webhookStatistics[].webhookName`	Название вебхука из проекта. Возвращается, когда вебхук успешно идентифицирован
`webhookStatistics[].integrationId`	UUID интеграции, к которой относится вебхук
`webhookStatistics[].integrationName`	Название интеграции из админки. Возвращается, когда `integrationId` найден в реестре интеграций. Если интеграция удалена, поле отсутствует, но `integrationId` приходит — это сигнал, что у вебхука есть устаревшая ссылка на интеграцию
`webhookStatistics[].totalCalls`	Количество вызовов за последние 60 минут (без учета повторных попыток). Значение всегда равно сумме успешных и ошибочных: `totalCalls = successCalls + failedCalls`
`webhookStatistics[].successCalls`	Количество вызовов с финальным успешным ответом получателя (HTTP 2xx, `WebhookLogStatus = Completed`)
`webhookStatistics[].failedCalls`	Количество вызовов, для которых все попытки (включая повторные) завершились ошибкой
`webhookStatistics[].totalRetries`	Количество повторных попыток сверх первой. Если все вызовы прошли с первой попытки, поле равно `0`
`webhookStatistics[].errorRate`	Доля ошибок в процентах, округленная до 2 знаков: `failedCalls / totalCalls × 100`
`webhookStatistics[].status`	Состояние записи (см. ниже)

Соотношение с экспортом логов

В выгрузке логов вебхуков каждая попытка — отдельная строка с полем WebhookLogRetryNumber (1 — первая попытка, от 2 — повторные). Тогда totalCalls равно числу уникальных записей в колонке WebhookLogTransactionId за окно агрегации, а totalRetries — общему числу строк минус число уникальных транзакций.

Значения поля `webhookStatistics[].status`

hasData — за последние 60 минут есть вызовы, статистика рассчитана;
noCallsInPeriod — вебхук и интеграция существуют, но за последние 60 минут вызовов не было. Все счетчики возвращаются равными 0;
notFound — указанные webhookId или integrationId не существуют в проекте, либо переданная пара не совпадает с реальной привязкой. Возникает, например, при опечатке в значении. В полях webhookId и integrationId возвращаются те же значения, что были в запросе. Все счетчики возвращаются равными 0.

Обработка ошибок

Список всех стандартных ошибок.

Ситуация	HTTP	Содержимое
Несуществующий `webhookId` или `integrationId`, либо несовпадение пары	200	Запись со статусом `status: "notFound"` в `webhookStatistics`. Остальные элементы запроса обрабатываются как обычно
Массив с пустым объектом `"webhooks":[{}]`	400	`ProtocolError`: «Each filter item must contain at least one of the fields: 'webhookId' or 'integrationId'»
Превышение лимита частоты опроса	429	`ProtocolError`: «Too many requests.». Подробнее
Кратковременная недоступность сервиса	503	`Service unavailable`. Реализуйте повторные попытки с экспоненциальной паузой между попытками не короче минуты

Окно агрегации

Окно — скользящие последние 60 минут от момента запроса. Каждый вызов попадает в счетчики через 30–90 секунд после приема Mindbox и покидает окно ровно через 60 минут. Изменить интервал нельзя — для других периодов используйте выгрузку логов.

Из-за задержки агрегации последние секунды могут не попасть в счетчики: для критичных алертов работайте с окном «60 минут назад минус 1 минуту», не используйте самые свежие данные.

Лимит частоты опроса

На проект действует ограничение: не более одного вызова метода в минуту. При нарушении возвращается HTTP 429.

Окно блокировки = 60 секунд от момента, когда клиент получил тело последнего успешного ответа.
Запросы внутри окна блокировки получают 429 и не продлевают окно, но и не дают новых данных — повторять запрос внутри окна не нужно.
Не поддерживаются заголовки Retry-After или X-RateLimit-*.

Безопасный интервал между запросами — 60 секунд + время ответа предыдущего запроса + небольшой запас. При среднем времени ответа около 1 секунды безопасный интервал равен 62 секундам.

Особенности неполных фильтров

При фильтре, в котором задано только одно из полей (webhookId или integrationId):

возвращаются только вебхуки, у которых был хотя бы один вызов за последние 60 минут;
вебхуки с totalCalls = 0 в список не попадают — для таких случаев используйте фильтр с явно заданной парой webhookId + integrationId, он вернет запись со status: "noCallsInPeriod".

Чтобы получить полный список — в том числе нулевые вебхуки — используйте явный фильтр webhookId + integrationId для каждого вебхука.

Как использовать статистику.

Last modified on October 30, 2026

Мониторинг операций Запуск сценария