automation
Как настроить вебхуки о депозитах из платёжного шлюза в алерты Telegram
Пошаговое руководство по передаче вебхуков о депозитах из платёжного шлюза в алерты Telegram: проверка подписи, дедупликация событий, учёт лимитов и уведомление команды.
Ключевые выводы
Для алерта о депозите нужны публичный эндпоинт, проверка подписи, дедупликация по ID события и вызов Telegram Bot API.
В документации Stripe сказано пропускать уже обработанные события и возвращать ответ 200, чтобы остановить повторные отправки.
Согласно Bots FAQ Telegram, бот не должен отправлять больше примерно одного сообщения в секунду в один чат.
Вебхуки и API crmchat позволяют привязать каждый депозит к контакту в Telegram.
Чтобы настроить вебхуки о депозитах, нужно зарегистрировать HTTPS-эндпоинт в платёжном шлюзе, проверять подпись каждого запроса, игнорировать дубликаты событий и пересылать короткое сообщение в чат Telegram через Bot API. Быстро отвечайте статусом успеха, а вызов Telegram делайте уже после этого.
Что нужно подготовить, прежде чем подключать платёжный шлюз к Telegram?
Вам понадобятся токен Telegram-бота, ID чата для алертов, небольшой сервер или инструмент автоматизации, способный принимать HTTPS-запросы, и секрет для подписи вебхуков из вашего шлюза.
Создайте бота через @BotFather, добавьте его в командную группу или канал и запишите ID чата. Токен бота и секрет подписи храните в переменных окружения, а не в коде.
Если не хотите писать сервер, в роли приёмника могут выступить n8n, Make или Zapier. Логика везде одна и та же.
Создайте бота в @BotFather и скопируйте токен.
Добавьте бота в чат для алертов и отправьте одно тестовое сообщение.
Возьмите ID чата из ответа метода getUpdates.
Сгенерируйте секрет подписи вебхуков в дашборде шлюза.
Разверните HTTPS-эндпоинт, принимающий POST-запросы.
Как убедиться, что вебхук о депозите настоящий?
Нужно пересчитать подпись по исходному телу запроса и вашему секрету, а затем сравнить её с заголовком подписи. Если значения не совпадают, отклоняйте запрос.
Используйте необработанное тело запроса, а не распарсенную и заново сериализованную версию, иначе дайджест будет другим. Сравнивайте функцией с постоянным временем выполнения.
Stripe добавляет временную метку в заголовок Stripe-Signature. Поскольку метка входит в подписываемые данные, злоумышленник не может изменить её, не сломав подпись, а ваше приложение может отклонять устаревшие запросы, как сказано в документации Stripe по вебхукам. Та же документация предостерегает от значения допуска 0: оно отключает проверку актуальности.
Другие шлюзы используют свои названия заголовков и алгоритмы, поэтому прочитайте страницу о подписях у вашего провайдера, прежде чем копировать эту логику.
Как избежать дублирующихся алертов о депозитах?
Сохраняйте ID каждого события и пропускайте любой ID, который уже обрабатывали. Шлюзы повторяют отправку при сбоях, поэтому один и тот же депозит может прийти не один раз.
В документации Stripe сказано пропускать уже обработанное событие и возвращать ответ 200, чтобы остановить дальнейшие повторы. Кроме того, Stripe генерирует новую подпись и временную метку при каждой повторной отправке, как указано в его документации по вебхукам, поэтому никогда не используйте подпись как ключ дедупликации. Используйте ID события.
Достаньте ID события из payload.
Найдите его в таблице базы данных или key-value хранилище.
Если он уже есть, верните ответ об успехе и остановитесь.
Если нет, сохраните ID, затем отправьте сообщение в Telegram.
Верните шлюзу ответ об успехе.
Сохраняйте ID до отправки или помечайте его как «в обработке», чтобы две параллельные доставки не прошли проверку одновременно.
Как отправить алерт в Telegram?
Вызовите метод sendMessage в Bot API, передав ID чата и короткий текст, собранный из полей депозита. Ограничьтесь суммой, валютой, клиентом и статусом.
Полезный алерт выглядит так: «Депозит подтверждён: сумма и валюта, пользователь @handle, ID заказа». Не включайте данные карт и всё, что вы не стали бы вставлять в групповой чат.
Учитывайте лимиты. Согласно Bots FAQ Telegram, бот не должен отправлять больше одного сообщения в секунду в один чат, а при всплесках в итоге появляются ошибки 429. В том же FAQ сказано, что массовые уведомления ограничены примерно 30 сообщениями в секунду, если не включены платные рассылки.
В дни с большим объёмом объединяйте мелкие депозиты в одно сводное сообщение, а крупные отправляйте сразу. Добавьте повторную попытку с нарастающей задержкой на случай ответов 429.
Как связать депозит с контактом в CRM?
Сопоставьте Telegram username или ID плательщика с записью в CRM и обновляйте эту запись, когда приходит платёж. Так отдел продаж получает контекст, а не просто уведомление.
В crmchat есть REST API, который позволяет получать список контактов с фильтром по telegram.username и telegram.id, а затем обновлять поля, например кастомное свойство со статусом депозита. Полный список эндпоинтов смотрите в API crmchat.
crmchat также умеет отправлять исходящие события через вебхуки, которые срабатывают на contact.created, contact.updated и contact.deleted и подписаны заголовком HMAC-SHA256. Это значит, что смена статуса депозита у контакта может запустить второй сценарий в n8n, Make или Zapier.
В базе знаний crmchat также отмечено, что платёж в Stripe или любой другой триггер может запустить последовательность аутрича в Telegram, так что первый депозит способен автоматически запустить приветственное сообщение.
Для команд из iGaming владельцы сделок уже получают алерты в Telegram, когда лид отвечает. Алерты о депозитах добавляют к этой картине платёжную сторону. Про платёжные риски читайте в материале как проверять высокорисковые процессинги.
Как протестировать и мониторить настройку?
Отправьте тестовые события из песочницы шлюза, убедитесь, что на каждый ID события приходит ровно одно сообщение в Telegram, а затем намеренно вызовите сбои и посмотрите, как работают повторные отправки. Сделайте это до запуска в продакшен.
Отправьте тестовое событие о депозите и убедитесь, что алерт пришёл один раз.
Повторите то же событие и убедитесь, что второго алерта нет.
Отправьте payload с неверной подписью и убедитесь, что он отклонён.
Намеренно верните ошибку сервера и посмотрите, как шлюз повторяет отправку.
Логируйте каждый ID события, статус и код ответа Telegram.
Настройте оповещение на случай, если депозитов нет необычно долго.
Если алерты перестали приходить, сначала проверьте сертификаты эндпоинта и права бота. Наше руководство про остановившиеся вебхуки Telegram разбирает сторону Telegram. Для крупных переводов добавьте шаг с участием человека: процесс подтверждения двумя людьми.
FAQ
Можно ли отправлять вебхуки о депозитах прямо в Telegram без сервера?
Напрямую нельзя: шлюз присылает payload в своём формате, а Telegram ожидает вызов Bot API. Используйте no-code инструмент, например n8n, Make или Zapier, как промежуточное звено, либо небольшую serverless-функцию.
Почему я получаю один и тот же алерт о депозите дважды?
Шлюзы повторяют отправку, если не получили ответ об успехе вовремя, так что дубликаты — это нормально. Сохраняйте ID событий и, как советует документация Stripe, пропускайте уже обработанные события и возвращайте ответ 200.
Сколько алертов в секунду может отправить Telegram-бот?
В Bots FAQ Telegram сказано держаться ниже примерно одного сообщения в секунду в одном чате. Массовые уведомления ограничены примерно 30 сообщениями в секунду без платных рассылок.
Публиковать алерты о депозитах в группе или в личном чате?
Используйте закрытую командную группу, где есть только те, кому нужно видеть платежи. Не включайте в сообщение чувствительные данные, а вместо этого давайте ссылку на запись в CRM.
