Что такое webhook? Как приложения уведомляют друг друга

Webhook — это автоматическое сообщение, которое один сервис отправляет вашему приложению в тот момент, когда что-то происходит. Когда платёж клиента проходит, Stripe отправляет webhook на адрес в вашем приложении с текстом «платёж прошёл, вот детали», и приложение реагирует: помечает заказ оплаченным, отправляет чек, открывает аккаунт. Коротко: API — это когда ваше приложение задаёт другому сервису вопрос; webhook — это когда другой сервис вызывает ваше приложение, чтобы что-то сообщить.

Почему это важно, когда вы создаёте приложение с помощью AI

Как только ваше приложение принимает платежи, получает данные из форм других сервисов или подключается к GitHub, Shopify или календарю, вы столкнётесь с webhook. Обычно это правильный способ узнать, что что-то произошло, но именно здесь приложения, созданные с помощью AI, чаще всего ошибаются:

• Обработчик принимает любой запрос, поэтому кто угодно может подделать событие «платёж прошёл».
• Приложение выдаёт доступ на странице перенаправления после оплаты, а не по webhook: поэтому те, кто закрыл вкладку раньше времени, не получают купленное, а те, кто нашёл адрес страницы успеха, получают его бесплатно.
• Одно и то же событие приходит дважды, и клиент получает два заказа или два письма.

Понимание того, как работают webhook, позволяет заранее попросить нужные защиты.

Бытовая аналогия: SMS о доставке

Узнать, пришла ли посылка, можно двумя способами. Можно каждые десять минут ходить к входной двери и проверять — это опрос (polling), когда приложение снова и снова вызывает API, чтобы спросить: «Что-нибудь новое?». Или курьер присылает SMS, когда доставит, — это webhook.

SMS явно удобнее, но только если ему можно доверять. Если кто угодно может прислать вам «посылка доставлена», нужен способ понять, что сообщение действительно от курьера. А если телефон был выключен, когда пришло сообщение, вы хотели бы, чтобы курьер попробовал снова позже. Эти две задачи — проверка и повторные попытки — и составляют большую часть сложности webhook.

Как работает webhook, шаг за шагом

1. Вы создаёте обработчик в бэкенде приложения: адрес вроде https://yourapp.com/webhooks/stripe, который принимает запросы POST.
2. Вы регистрируете этот адрес у провайдера и выбираете события, которые хотите получать (например, «оформление оплаты завершено» и «подписка отменена»).
3. Провайдер выдаёт секрет для подписи. Вы сохраняете его как секрет на сервере — см. переменные окружения и секреты.
4. Происходит событие. Провайдер отправляет HTTP-запрос на ваш адрес с JSON-телом, описывающим событие, и заголовком подписи.
5. Приложение проверяет подпись, записывает ID события, быстро отвечает кодом успеха (200) и только потом выполняет работу.
6. Если приложение не ответило успехом, многие провайдеры пробуют отправить событие позже.

Подписи

Подпись доказывает, что запрос пришёл от провайдера и не был изменён. Stripe, например, вычисляет HMAC (своего рода ключевой отпечаток) по SHA-256 от тела запроса и временной метки, используя секрет подписи, и отправляет результат в заголовке Stripe-Signature. Ваше приложение делает то же вычисление со своей копией секрета; если результаты совпадают, запрос подлинный. Поскольку временная метка тоже подписана, можно отклонить старые запросы, которые кто-то записал и повторно отправил позже: по документации Stripe на сентябрь 2026 года, его библиотеки по умолчанию допускают отклонение в пять минут.

Одна практическая деталь: подпись вычисляется по исходному телу запроса. Если фреймворк разбирает и переформатирует JSON до проверки, проверка не пройдёт. Это очень распространённая ошибка.

Повторы, дубликаты и порядок

Провайдеры отличаются, поэтому сверяйтесь с документацией каждого. На сентябрь 2026 года:

Документация Stripe также говорит, что события не гарантированно приходят в том порядке, в каком произошли, и что одно и то же событие может изредка прийти более одного раза, поэтому рекомендуется отслеживать ID событий.

Общий урок справедлив для любого провайдера: события могут прийти с опозданием, более одного раза и не по порядку. Обработчик должен быть идемпотентным — обработка одного и того же события дважды даёт такой же результат, как однократная обработка.

Пример: открытие доступа к платному курсу

Вы продаёте онлайн-курс. Студент нажимает Купить, платит на размещённой странице оплаты Stripe и возвращается на ваш сайт.

Хрупкий способ: страница «Спасибо» открывает курс. Если студент закроет браузер во время перенаправления, он заплатил, но доступа нет. Если кто-то угадает адрес страницы «Спасибо», он получит доступ без оплаты.

Способ через webhook:

1. Когда Stripe подтверждает платёж, он отправляет событие checkout.session.completed на /webhooks/stripe.
2. Ваш бэкенд проверяет подпись секретом. Если проверка не прошла, он отвечает 400 и ничего не делает.
3. Он проверяет, не обработан ли уже этот ID события. Если да, отвечает 200 и останавливается.
4. Он сохраняет ID события, отвечает 200, а затем открывает студенту доступ и отправляет приветственное письмо.
5. На странице «Спасибо» просто написано «Оплата получена — курс появится через минуту», и она проверяет статус доступа студента.

Позже, если подписка отменена или карта отклонена, другие события webhook говорят приложению убрать доступ или приостановить его. Так подписочные продукты остаются в синхронизации с биллингом — см. что такое SaaS и как добавить оплату в приложение.

Ключевые термины

• Endpoint (обработчик): адрес в вашем приложении, который принимает webhook.
• Событие / payload: что произошло и данные, которые это описывают (обычно JSON).
• Секрет подписи: общий секрет для проверки подписей.
• Идемпотентность: безопасность повторного выполнения с тем же результатом.
• Polling (опрос): регулярные запросы к API за изменениями вместо ожидания webhook.
• Туннель: инструмент, который даёт ноутбуку временный публичный адрес, чтобы webhook могли до него дойти во время разработки.

Частые ошибки и заблуждения

• Отсутствие проверки подписей. Адрес обработчика не является секретом. Именно проверка делает запрос надёжным.
• Медленная работа до ответа. Отправка писем или генерация PDF до ответа может вызвать таймаут, который запускает повторы, которые порождают дубликаты.
• Предположение «ровно один раз и по порядку». Записывайте ID событий и не полагайтесь на порядок прихода.
• Использование адреса предпросмотра. Webhook нужен стабильный публичный адрес. Закрытые предпросмотры и localhost недоступны из интернета; используйте опубликованный адрес (или туннель во время тестов).
• Смешивание тестовых и боевых секретов. Провайдеры часто выдают разные секреты подписи для тестового и боевого режимов. Храните оба и используйте нужный.
• Слепое доверие данным из payload для важных решений. Для действий с высокой ценой ошибки разумно после получения события запросить актуальное состояние через API провайдера.

Что попросить у AI-конструктора

Добавь на сервере эндпоинт POST /webhooks/stripe. Проверяй подпись Stripe по исходному телу запроса и секрету STRIPE_WEBHOOK_SECRET. Отклоняй неверные подписи с кодом 400. Сохраняй ID каждого события и пропускай уже обработанные. Отвечай 200 быстро, затем обработай checkout.session.completed: пометь заказ оплаченным и отправь чек. Логируй тип события. Не выдавай доступ со страницы успешной оплаты.

Затем проверьте: отправьте тестовое событие из панели провайдера, отправьте то же событие повторно и отправьте запрос с неверной подписью. Изменения должно внести только первое.

Webhook в Mythex

В Mythex нет отдельного сервиса для webhook: вы просите агента добавить эндпоинт webhook в собственный бэкенд вашего приложения и указываете провайдеру ваш опубликованный адрес, так как webhook нужен публичный адрес. Секрет подписи добавляется в секреты проекта, и если вы его меняете в работающем приложении, публикуете снова. В рецепте документации обработка webhook есть стартовый промпт, а шаблоны магазинов — хорошая отправная точка для приложений, которые принимают платежи.

Вопросы