Сначала проверьте
- Тариф активен? При истёкшем тарифе вебхуки не отправляются вовсе — и это выглядит как «всё сломалось».
- Недавно привязывали организацию или переключали режим? Ключ и вебхук могли перегенерироваться — перезабейте URL и секрет.
- Тест из кабинета. Кнопка «Проверить уведомления» (тест-вебхук) — если тест доходит, проблема не в доставке, а в вашем обработчике.
Ветки диагностики
| Признак | Вероятная причина (частота по данным поддержки) | Что сделать | Подробнее |
|---|---|---|---|
| Вебхуки пропали после привязки организации / перехода в рабочий режим | Ключ и вебхук перегенерировались — чаще всего | Перезабить Webhook URL и секрет в Настройках → «Подключения», обновить ключ в коде | Раздел «Когда ключи „внезапно“ перестают работать» в «API-ключ и вебхук-секрет» |
| В вебхук-логах «не доставлено», таймаут | Ваш URL недоступен из интернета — часто | Проверить curl -X POST https://ваш-url с внешней машины; localhost не подойдёт — нужен туннель |
«Как тестировать локально?» в «Настройке вебхуков» |
| «Validation failed» при сохранении URL | Пробел до или после URL — редкий случай | Убрать пробелы, сохранить заново | — (это всё решение) |
Подпись «не сходится» / bad-signature |
Секрет не установлен или проверяется не по raw body — часто у новых | Сгенерировать секрет (кнопка появляется после ввода Webhook URL), HMAC считать по сырому телу | «Как проверить подпись: главное правило — raw body» в «Настройке вебхуков» |
| Молчат и вебхуки, и создание счетов | Тариф истёк — редко | Продлить: кабинет → «Мой тариф» | Тарифы и комиссия |
webhook_status: paused или disabled в списке ключей |
Circuit breaker после серии неудачных доставок | Починить доступность URL → нажать тест-вебхук — канал оживёт | «Circuit breaker…» в «Настройке вебхуков» |
| Несколько организаций — вебхук приходит «не туда» | Перепутаны ключи организаций — редко | Вебхук идёт на URL ключа-создателя счёта: сверьте key_hint, каким ключом создаёте счета |
API-ключ и вебхук-секрет |
Быстрая самодиагностика за 3 минуты
- Нажмите «Проверить уведомления» в кабинете. Пришёл
webhook.test— доставка работает, ищите проблему в обработчике (например, отвечаете не 2xx или дольше 5 секунд). - Тест не пришёл — посмотрите вебхук-логи: там виден HTTP-код ответа вашего сервера или причина («Таймаут соединения»).
- Логи пустые — уведомления не отправляются вовсе: проверьте тариф и то, что Webhook URL вообще сохранён у того ключа, которым создаются счета.
Для вашего ИИ-агента
Проверяйте: webhook_status в списке API-ключей (active | paused | disabled), вебхук-логи и HTTP-коды ответов; подпись — заголовок X-Webhook-Signature: sha256=<hex>, HMAC-SHA256 по raw body; успех доставки = любой 2xx быстрее 5 секунд; ретраев 11 с интервалами до 1 часа.
Частые вопросы
Мой сервер лежал час — вебхуки потеряны?
Нет: система делает 11 попыток с нарастающим интервалом (от 10 секунд до 1 часа). После исчерпания — ручной повтор из вебхук-логов кабинета.
Почему вебхуки пропали именно после привязки организации?
При привязке организации или смене режима API-ключ и вебхук могут перегенерироваться. Перезабейте URL и секрет и обновите ключ в коде — это самая частая причина «молчания».
В каком заголовке приходит подпись?
X-Webhook-Signature: sha256=<hex> — HMAC-SHA256 от сырого тела запроса. Проверка по перекодированному JSON не сойдётся.
Можно ли тестировать вебхуки локально?
Да, через туннель (например ngrok): нужен публичный HTTPS-URL. localhost в настройках не заработает.
Что значит webhook_status: paused?
Circuit breaker: после ≥5 неудачных доставок канал ставится на паузу (при ≥50 — отключается). Сбрасывается любой успешной доставкой или тест-вебхуком из кабинета.