Вебхук (Webhook)

Вебхук — это способ, которым одна система в реальном времени уведомляет другую систему, в момент, когда что-то происходит, отправляя HTTP POST-запрос на URL, заранее зарегистрированный принимающей системой — обратное типичному использованию API, где клиент постоянно опрашивает сервер вопросом «что-нибудь изменилось?». С вебхуками сервер отправляет уведомление только тогда, когда действительно есть что сообщить, что гораздо эффективнее опроса и обеспечивает почти мгновенное уведомление вместо задержки, присущей интервалу опроса. Почти каждая крупная API-ориентированная платформа поддерживает вебхуки: Stripe запускает вебхук при успешном платеже, GitHub запускает его при открытии pull request, а SaaS-инструменты, соседствующие с Anthropic, обычно используют вебхуки для уведомления нижестоящей системы о завершении длительной задачи ИИ (например, задачи пакетной обработки). Почему это важно для разработчиков AI/SaaS: вебхуки — стандартный паттерн интеграции для соединения независимых систем в реальном времени без необходимости постоянного опроса друг друга — они являются основой платформ автоматизации вроде Zapier и Make.com и необходимы для всего событийно-ориентированного, например обновления CRM в момент неудачного платежа Stripe или запуска нижестоящей обработки в момент завершения пользователем онбординга. Поскольку эндпоинты вебхуков — это публичные URL, принимающие произвольные POST-запросы, корректная проверка подлинности запроса (обычно через проверку подписи с использованием общего секрета) критически важна — непроверенный эндпоинт вебхука представляет реальный риск безопасности, поскольку любой, кто обнаружит URL, может отправлять поддельные события. Как это работает: принимающее приложение регистрирует URL у отправляющей платформы (часто через панель или вызов API) и указывает, о каких событиях хочет получать уведомления. Когда это событие происходит, отправляющая платформа отправляет HTTP POST на зарегистрированный URL с JSON-полезной нагрузкой, описывающей событие; принимающий эндпоинт должен быстро ответить (обычно в течение нескольких секунд) кодом состояния 2xx, чтобы подтвердить получение, иначе отправитель повторит попытку с задержкой, предполагая, что доставка не удалась. Практический пример: SaaS-компания хочет предоставить пользователю доступ к платной функции в момент завершения оформления заказа в Stripe. Они регистрируют у Stripe эндпоинт вебхука `POST /webhooks/stripe`, подписанный на событие `checkout.session.completed`. Когда клиент платит, Stripe отправляет POST-запрос на этот URL с JSON-полезной нагрузкой вроде `{"type": "checkout.session.completed", "data": {"object": {"customer_email": "user@example.com", "amount_total": 4900}}}`. Эндпоинт проверяет заголовок подписи Stripe в запросе относительно своего секрета вебхука, чтобы подтвердить, что запрос действительно от Stripe (а не подделан), затем обновляет аккаунт этого пользователя на `plan: "pro"` в своей базе данных и возвращает `200 OK` — всё это происходит примерно в течение секунды от фактического платежа, без какого-либо опроса.