Сначала проверьте
- Тариф активен? При истёкшем тарифе любой write-запрос отбивается
403 tariff_inactive, а фоновая синхронизация организации останавливается: новых переходов статуса нет, значит нет и вебхуков. Проверка — кабинет → «Мой тариф». - Ключ и вебхук-настройки сменились? Сами по себе они не меняются, и переключение sandbox↔рабочий режим в своём кабинете их не трогает. Когда значения всё же перестают действовать — разобрано в «API-ключ и вебхук-секрет».
Ветки диагностики
| Что вы видите | Причина | Что сделать | Подробнее |
|---|---|---|---|
В GET /webhook-logs строк по счёту нет вообще |
Доставка не запускалась: у ключа-создателя пустой webhook_url, либо webhook_status = paused/disabled, либо истёк тариф |
Сверить key_hint ключа, которым создаются счета; посмотреть webhook_status в списке API-ключей; проверить тариф |
«Circuit breaker…» в «Настройке вебхуков» |
В логе error_message: redirect not followed: HTTP 302 |
301/302/303 — недоставка без ретрая, типично http:// в webhook_url при редиректе сервера на https:// |
Прописать сразу конечный https-адрес без переадресации; 307/308 доставляются штатно |
«Ретраи» в «Настройке вебхуков» |
| В логе таймаут или нет ответа | URL недоступен из интернета | curl -X POST https://ваш-url с внешней машины; localhost не подойдёт — нужен туннель |
«Как тестировать локально?» в «Настройке вебхуков» |
В логе response_status: 401 |
Подпись считается не по raw body или не тем секретом, либо на URL стоит своя авторизация | Сгенерировать вебхук-секрет (кнопка появляется после сохранения Webhook URL), HMAC — по сырому телу, авторизацию с эндпоинта снять | «Как проверить подпись: главное правило — raw body» в «Настройке вебхуков» |
webhook_status: paused или disabled в списке ключей |
Circuit breaker: ≥5 неудач — 5 мин, ≥10 — 30 мин, ≥20 — 2 ч, ≥50 — отключение | Починить доступность URL → «Проверить уведомления»: успешная доставка сбрасывает счётчик | «Circuit breaker…» в «Настройке вебхуков» |
403 tariff_inactive на создании счёта |
Тариф истёк: write-запросы заблокированы, фоновая синхронизация организации остановлена — новых переходов статуса нет | Продлить: кабинет → «Мой тариф». В теле 403 приходят expires_at и reason — дату читайте вместе с причиной: при reason: cancelled она может быть в будущем |
Тарифы и комиссия |
| «Validation failed» при сохранении URL | Пробел в URL, приватный IP, либо в рабочем режиме до одобрения анкеты — webhook_url_requires_domain (IP) / webhook_url_tunnel_forbidden (ngrok и подобные) |
Убрать пробелы, указать публичный HTTPS на постоянном домене своего сервиса | «Как тестировать локально?» в «Настройке вебхуков» |
| Ключ и вебхук-настройки внезапно сменились | Перегенерация, повторная партнёрская выдача ключа или перенос организации на другой аккаунт | Взять новые значения и обновить их во всех интеграциях сразу | Раздел «Когда ключи „внезапно“ перестают работать» в «API-ключ и вебхук-секрет» |
Быстрая самодиагностика за 3 минуты
- Нажмите «Проверить уведомления» в кабинете. Пришёл
webhook.test— доставка работает, ищите проблему в обработчике (например, отвечаете не 2xx или дольше 5 секунд). - Тест не пришёл — посмотрите вебхук-логи: там виден HTTP-код ответа вашего сервера или причина («Таймаут соединения»).
- Логи пустые — доставка не запускалась: проверьте
webhook_urlиwebhook_statusу того ключа, которым создаются счета (сверьтеkey_hint), затем тариф.
Для вашего ИИ-агента
Проверяйте по порядку: GET /api/v1/webhook-logs?invoice_id=… (фильтры event, status=failed) → у ключа-создателя счёта webhook_url и webhook_status (active | paused | disabled) → тариф. В строке лога значимы response_status, response_time_ms, error_message. Успех доставки = любой 2xx быстрее 5 секунд; 301/302/303 — недоставка без ретрая. Проверка подписи и сетка ретраев — в «Настройке вебхуков».