В стандартном сценарии работы с API ProverkaCheka ваша система отправляет чек и ожидает ответ. Но что если проверка инициируется через Telegram-бот менеджером, а результат нужен в вашей CRM или бэк-офисе? Здесь на помощь приходят webhook-уведомления — механизм мгновенной доставки результатов проверки в любую внешнюю систему.
В этой статье мы разберём архитектуру webhook-интеграции, настройку на стороне вашего сервера, обеспечение безопасности и обработку различных сценариев.
Что такое webhook и зачем он нужен
Webhook — это HTTP-запрос, который ProverkaCheka отправляет на ваш сервер каждый раз, когда происходит проверка чека. Вместо того чтобы постоянно опрашивать API на предмет новых проверок (polling), вы получаете уведомление мгновенно (push).
Сравнение подходов
| Параметр | Polling (опрос) | Webhook (push) |
|---|---|---|
| Задержка | Зависит от интервала опроса | Мгновенно (менее 1 сек) |
| Нагрузка на сервер | Постоянные запросы, даже без данных | Запрос только при наличии события |
| Сложность реализации | Проще (цикл опроса) | Требует публичный endpoint |
| Масштабируемость | Плохая при больших объёмах | Линейная |
Типичные сценарии использования
- Синхронизация с CRM — менеджер проверяет чек в боте, результат автоматически появляется в сделке Kommo/Bitrix24
- Обновление статуса заказа — интернет-магазин мгновенно подтверждает оплату после проверки
- Уведомления команды — результат проверки отправляется в Slack, Discord или корпоративный чат
- Бухгалтерский учёт — данные проверки автоматически записываются в учётную систему
Архитектура webhook-интеграции
Процесс работает следующим образом:
- Регистрация URL — вы указываете адрес вашего сервера (webhook URL) в настройках аккаунта ProverkaCheka.
- Проверка чека — чек загружается через API, бот или виджет. Проверка проходит как обычно.
- Отправка уведомления — после обработки чека ProverkaCheka отправляет POST-запрос на ваш webhook URL с полными данными проверки.
- Подтверждение получения — ваш сервер отвечает HTTP 200, подтверждая получение уведомления.
Требование: Ваш webhook URL должен быть доступен из интернета по HTTPS. Самоподписанные сертификаты не поддерживаются. Используйте Let's Encrypt или Cloudflare для получения бесплатного SSL-сертификата.
Настройка webhook-сервера
Для получения webhook-уведомлений вам нужен HTTP-сервер с публичным endpoint. Вот ключевые требования к серверу:
Требования к endpoint
- Протокол: HTTPS (HTTP не поддерживается из соображений безопасности)
- Метод: POST — все уведомления приходят POST-запросом
- Content-Type:
application/json— тело запроса содержит JSON с данными проверки - Время ответа: менее 5 секунд — если ваш сервер не ответит вовремя, отправка считается неудачной
- Код ответа: HTTP 200 — любой другой код инициирует повторную отправку
Структура тела запроса
Webhook-запрос содержит те же данные, что и ответ API при проверке чека:
| Поле | Тип | Описание |
|---|---|---|
event |
string | Тип события: receipt.checked |
status |
string | Результат: valid, invalid, duplicate, iin_mismatch |
check_number |
string | Номер чека из Kaspi |
amount |
float | Сумма транзакции в тенге |
seller |
string | Название продавца |
date |
string | Дата транзакции (ISO 8601) |
timestamp |
string | Время проверки (ISO 8601) |
is_duplicate |
boolean | Признак дубликата |
Обеспечение безопасности
Webhook-endpoint доступен из интернета, поэтому важно убедиться, что запросы приходят именно от ProverkaCheka, а не от злоумышленника.
Проверка подписи запроса
Каждый webhook-запрос содержит заголовок с цифровой подписью. Ваш сервер должен проверять эту подпись перед обработкой данных. Подпись вычисляется на основе тела запроса и секретного ключа, известного только вам и ProverkaCheka.
Дополнительные меры безопасности
- Белый список IP — ограничьте доступ к webhook-endpoint только IP-адресами ProverkaCheka
- Таймаут — отклоняйте запросы старше 5 минут (по полю
timestamp) - Идемпотентность — обрабатывайте повторные уведомления с тем же
check_numberбез побочных эффектов - Rate limiting — ограничьте количество запросов к endpoint, чтобы защититься от DDoS
При повторной отправке (retry) ваш сервер может получить одно и то же уведомление несколько раз. Используйте check_number как ключ идемпотентности: если вы уже обработали уведомление с этим номером — верните 200 без повторной обработки.
Механизм повторной отправки (retry)
Если ваш сервер не ответил HTTP 200 в течение 5 секунд, ProverkaCheka считает отправку неудачной и инициирует повторные попытки.
Расписание retry
| Попытка | Задержка | Суммарное время |
|---|---|---|
| 1-я повторная | 10 секунд | 10 сек |
| 2-я повторная | 1 минута | 1 мин 10 сек |
| 3-я повторная | 5 минут | 6 мин 10 сек |
| 4-я повторная | 30 минут | 36 мин 10 сек |
| 5-я повторная | 2 часа | ~2,5 часа |
После 5 неудачных попыток уведомление помечается как недоставленное. Вы можете запросить повторную отправку через поддержку.
Практические сценарии интеграции
Сценарий 1: Автоматическое подтверждение заказа
Интернет-магазин принимает оплату через Kaspi. Покупатель загружает чек через форму на сайте. API обрабатывает чек, а webhook отправляет результат в систему управления заказами. При статусе valid заказ автоматически переходит в статус «Оплачен», менеджер получает уведомление, покупателю отправляется подтверждение.
Сценарий 2: Синхронизация с бухгалтерией
Менеджер проверяет чеки через Telegram-бот в течение дня. Каждый результат проверки через webhook записывается в бухгалтерскую систему: сумма, дата, номер чека, имя продавца. В конце месяца бухгалтер получает готовый реестр всех подтверждённых оплат.
Сценарий 3: Уведомления в корпоративный чат
Webhook-endpoint принимает уведомление и пересылает его в Slack-канал или Telegram-группу. Команда видит каждую проверку в реальном времени: «Чек QR13973837513 на 15 000 ₸ от ИП Алибеков — подтверждён». Подозрительные чеки (дубликаты, несовпадение ИИН) выделяются красным.
Обработка ошибок на стороне webhook
Ваш webhook-сервер должен быть устойчив к ошибкам. Вот рекомендации:
- Быстрый ответ — отвечайте HTTP 200 сразу после получения данных, обработку выполняйте асинхронно в фоне
- Валидация данных — проверяйте наличие обязательных полей перед обработкой
- Логирование — записывайте все входящие запросы для отладки и аудита
- Мониторинг — отслеживайте задержки и ошибки обработки, настройте алерты при сбоях
Золотое правило: Отвечайте 200 быстро, обрабатывайте данные в фоне. Если обработка занимает больше 1-2 секунд — поставьте задачу в очередь (Redis, RabbitMQ, или просто в базу данных) и обрабатывайте асинхронно.
Тестирование webhook
Перед запуском в продакшн протестируйте webhook в безопасной среде:
- Используйте тестовый URL — сервисы вроде webhook.site позволяют просмотреть входящие запросы без настройки сервера.
- Проверьте все статусы — убедитесь, что ваш сервер корректно обрабатывает valid, invalid, duplicate и iin_mismatch.
- Симулируйте ошибки — проверьте, что при таймауте вашего сервера retry-механизм работает корректно.
- Нагрузочный тест — отправьте несколько десятков уведомлений одновременно, чтобы проверить устойчивость.
Итоги
Webhook-интеграция превращает ProverkaCheka из инструмента ручной проверки в компонент вашей автоматизированной экосистемы. Результаты проверок мгновенно попадают в CRM, бухгалтерию, корпоративный чат — без ручного копирования и переключения между окнами.
Начните с простого endpoint, который записывает данные в базу. Затем добавьте проверку подписи, идемпотентность и асинхронную обработку. Качественная webhook-интеграция экономит часы ручной работы ежедневно.