Copy page

Разное

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

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

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

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

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

---

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ответ

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

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

Поле	Описание
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	Состояние записи (см. ниже)

Значения поля 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 минут. Изменить интервал нельзя — для других периодов используйте выгрузку логов.

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

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

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

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

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

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

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