Вебхуки о готовности и изменениях отчёта

Вебхук уведомляет вашу систему, когда отчёт сформирован или изменён. SEO Reports отправляет POST с JSON на адрес, настроенный в кабинете. Получатель принимает событие и при необходимости скачивает файл через API.

Настройте получателя

Подготовьте доступный сервису HTTP-обработчик. Для передачи данных используйте HTTPS.
Откройте «API & MCP» → API и найдите поле адреса уведомлений.
Укажите полный URL и нажмите «Сохранить» — настройка общая для всего аккаунта.
Соберите новый отчёт или сохраните в нём правку и проверьте событие. Для отключения очистите адрес и сохраните настройку.

Вкладка API: под таблицей ключей — поле адреса уведомлений о готовности и изменениях отчётов и кнопка «Сохранить».

Когда приходят события

Событие	Когда отправляется
`report_generated`	Завершилась сборка отчёта, в том числе повторная генерация.
`report_changed`	Сохранена правка отчёта: кнопкой «Сохранить» в редакторе или изменением структуры через API, в том числе из MCP-ассистента.

Каждое сохранение создаёт отдельное событие со своим номером правки: несколько правок подряд не объединяются в одно уведомление. Чтение отчёта и выгрузка файла событий не создают.

Обратите внимание. Событие о правке создаётся, только если адрес вебхука уже сохранён. Правки, сделанные до настройки адреса, не отправляются.

Формат события

Тело report_changed такое же, как у report_generated, и дополнительно содержит data.revision.

json

{
  "event": "report_changed",
  "event_id": "e4c07a2f9b1d4e3a8c5f6b7d2a1e9c30",
  "data": {
    "project_id": "35328",
    "domain": "example.ru",
    "report_id": "35328.a3f1c9e84b2d7061fe5c8a94d20b3e77",
    "revision": 4,
    "export_link": "https://seo-reports.ru/api/reports/35328.a3f1c9e84b2d7061fe5c8a94d20b3e77/export/word"
  }
}

Поле	Значение
`event`	`report_generated` — отчёт собран, `report_changed` — сохранена правка.
`event_id`	Идентификатор для обработки дублей.
`data.project_id`	Идентификатор проекта — тот же `project_id`, что в API.
`data.domain`	Адрес проекта.
`data.report_id`	Идентификатор отчёта — тот же `report_id`, что в API.
`data.revision`	Только в `report_changed`: номер, который получила эта правка. Совпадает с `revision` в ответе на сохранение.
`data.export_link`	Адрес выгрузки Word, требующий Bearer-ключа.

Обработка события

Проверьте тип события и структуру JSON. Если передан event_id, сохраните его.
Запишите событие в очередь или хранилище. На повтор уже принятого события отвечайте успешно, но не запускайте повторную его обработку.
Быстро верните успешный HTTP-ответ, обычно 200 или 204. Скачивание и дальнейшую обработку выполняйте отдельно.
По data.report_id проверьте карточку и предупреждения. Для скачивания по export_link используйте ключ с правами reports:read.

Таймаут запроса к получателю — 30 секунд. Вебхук не содержит ключ и не открывает отчёт гостям. Исходящий POST не подписывается HMAC и не содержит Bearer-авторизации.

Совет. Перед передачей ключа проверяйте, что export_link ведёт на ожидаемый HTTPS-домен SEO Reports и путь /api/reports/. Не отправляйте ключ произвольному URL из непроверенного входящего запроса. Подтверждайте известный отчёт запросом API.

Свои правки и порядок событий

По data.revision интеграция узнаёт, что правку через API сделала она сама, и отбрасывает события, пришедшие не по порядку.

После своего сохранения через API запишите revision из ответа как последний учтённый номер отчёта. Событие report_changed с этим номером — отклик на вашу правку, повторно её не обрабатывайте.
Принимайте report_changed, только если его revision больше последнего учтённого, и обновляйте сохранённый номер. Событие с меньшим номером пришло не по порядку: более новая правка уже учтена.
В report_generated номера нет. После сборки берите актуальный revision из карточки отчёта.

Повторы и дубли

При таймауте, сетевой ошибке или ответе 4xx/5xx предусмотрено до восьми попыток доставки. Паузы между попытками увеличиваются: 1 минута, 5 минут, 15 минут, 1 час, 3 часа, 6 часов и 12 часов. Если все попытки исчерпаны, событие отмечается неуспешным. Доставка постоянно недоступному получателю не гарантируется.

Повтор возможен и после принятия события, если ответ потерялся. Дедупликацию делайте по event_id, а не report_id: новая сборка или правка того же отчёта порождает новое событие.

Если уведомление не пришло

Проверьте сохранённый адрес и доступность обработчика из интернета.
Убедитесь, что завершилась новая сборка, а не вернулся существующий результат.
Для report_changed убедитесь, что правка сохранена и адрес вебхука был задан до неё.
Проверьте логи получателя: ответ должен прийти до таймаута.
До восстановления вебхука отслеживайте готовность и revision GET-запросом карточки отчёта.

Выгрузка описана в справочнике, ошибки API — в диагностике.

Помогла статья?

← ПредыдущаяСправочник методов API Следующая →Ошибки, лимиты и диагностика API

← В категорию «API & MCP»В справочный центр