> Источник: https://apipay.kz/guides/webhook-ne-prihodit · Обновлено: 2026-07-06 · apipay.kz
> ApiPay — независимый сервис приёма платежей поверх вашего Kaspi Pay.

# Вебхук ApiPay не приходит — как найти причину?

**TL;DR.** Диагностика идёт по журналу доставок, а не по догадкам. Порядок: (1) `GET /api/v1/webhook-logs?invoice_id=…` — есть ли строка доставки по счёту; (2) строк нет — смотрите у ключа-создателя счёта `webhook_url` и `webhook_status` (`active | paused | disabled`), плюс активность тарифа; (3) строки есть — читайте `response_status`, `response_time_ms` и `error_message`: там видно, ответил ли ваш сервер `2xx` быстрее 5 секунд. Кнопка «Проверить уведомления» шлёт `webhook.test` на тот же URL с боевой подписью.

## Сначала проверьте

1. **Тариф активен?** При истёкшем тарифе любой write-запрос отбивается `403 tariff_inactive`, а фоновая синхронизация организации останавливается: новых переходов статуса нет, значит нет и вебхуков. Проверка — кабинет → «Мой тариф».
2. **Ключ и вебхук-настройки сменились?** Сами по себе они не меняются, и переключение sandbox↔рабочий режим в своём кабинете их **не трогает**. Когда значения всё же перестают действовать — разобрано в «[API-ключ и вебхук-секрет](/guides/api-klyuch-i-webhook-secret)».

## Ветки диагностики

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

## Быстрая самодиагностика за 3 минуты

1. Нажмите «Проверить уведомления» в кабинете. Пришёл `webhook.test` — доставка работает, ищите проблему в обработчике (например, отвечаете не 2xx или дольше 5 секунд).
2. Тест не пришёл — посмотрите вебхук-логи: там виден HTTP-код ответа вашего сервера или причина («Таймаут соединения»).
3. Логи пустые — доставка не запускалась: проверьте `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` — недоставка без ретрая. Проверка подписи и сетка ретраев — в «[Настройке вебхуков](/guides/nastroyka-webhookov-apipay)».

---

ApiPay — независимый сервис и не аффилирован с АО «Kaspi Bank». Kaspi и Kaspi Pay — товарные знаки их правообладателя.
База знаний: https://apipay.kz/guides