Docs/Разработчикам/Вебхуки

Вебхуки

Сейчас в платформе работает один входящий вебхук — от ЮKassa, для подтверждения платежей. Исходящих вебхуков для внешних подписчиков (например, «новая карточка появилась у меня в проекте» → ваш сервер) пока нет — они в роадмапе вместе с публичной версией API.

Текущий статус

в разработке

Исходящих вебхуков с подписями и retry-логикой пока нет. Если нужно реагировать на события в проекте на стороне вашей CRM или Telegram-бота — пока используйте встроенные CRM-интеграции или email-уведомления из настроек уведомлений.

Входящий вебхук от ЮKassa

только для платежей

Когда у вас проходит платёж за Pro, ЮKassa дёргает наш URL — POST /api/payments/yookassa/webhook. По этому событию мы активируем подписку, продлеваем срок и начисляем реферальный бонус, если он был.

🔒

Что приходит в теле

Тело запроса не доверяем и не используем напрямую — извлекаем только payment.id, после чего идём в API ЮKassa и сами запрашиваем подтверждённый статус.

↩️

Ответ всегда 200

Мы возвращаем 200 OK даже при внутренних ошибках — чтобы ЮKassa не уходила в бесконечный retry. Сами разбираемся в логах и при необходимости активируем подписку вручную.

Этот эндпоинт — служебный, для пользователей платформы делать с ним ничего не нужно. Описан здесь только для прозрачности: чтобы было понятно, что подписка активируется именно по подтверждению из ЮKassa, а не «на честное слово» от клиента.

Что планируем

исходящие вебхуки

В рамках публичной версии API хотим дать возможность подписываться на события платформы из вашего сервиса. Минимальный набор, который видим сейчас:

recommendation.created

Новая карточка-рекомендация появилась в проекте. Полезно, чтобы автоматически ставить задачу в трекер или присылать в Telegram.

analysis.completed

Завершился прогон одного из агентов. Удобно для собственного дашборда или цепочек автоматизации.

billing.subscription.updated

Изменился тариф или статус подписки (продление, отмена, истечение). Для синхронизации с внутренней биллинговой системой агентств.

Подписи (HMAC-SHA256), retry с экспоненциальной задержкой и журнал доставок — будут обязательно. Если важно, под какой именно сценарий вам нужен исходящий вебхук — напишите на контакт поддержки, добавим в очередь по фактическому спросу.