Вебхук: что это и как настроить: полный гайд

Вебхук не дошёл, и оплата клиента потерялась. Или заявка с сайта ушла в пустоту, а менеджер отдела продаж узнал об этом через сутки. Знакомо? Чтобы разобраться, почему так происходит и как этого избежать, нужно сначала понять принцип работы вебхука и чем он отличается от API.

Seopapa: сервис для продвижения сайтов в ТОП-1 Яндекс

Начать продвижение

Как работает вебхук и чем отличается от API

Вебхук (webhook) — это механизм обратных вызовов, при котором сервер сам отправляет данные на указанный URL, когда происходит событие. Никакого постоянного опроса, никаких лишних запросов. Реакция на событие — и сразу HTTP-запрос с информацией в формате JSON на заранее указанный адрес.

Самая понятная аналогия — SMS-уведомление от банка. Можно каждые 5 минут входить в приложение и проверять баланс, а можно просто подключить уведомления: произошло списание — банк сам отправляет сообщения на телефон. Вебхук работает по тому же принципу: при наступлении события система отправляет HTTP-запрос (обычно POST) на публичный URL, который был указан при настройке.

Как работает API и в чём разница

Когда приложение использует API, оно само отправляет запросы к серверу и запрашивает данные. Допустим, интернет-магазин хочет получить информацию о новых заказах. API работает так: каждые 2–3 минуты код отправляет запрос «есть новые заказы?». В 95% случаев ответ — пустой. Это polling, то есть расточительный способ обмена данными: нагрузка на сервер растёт, время тратится впустую, а задержка между реальным событием и его обработкой может достигать 2–3 минуты.

Вебхук — зеркальная история. Не приложение отправляет запросы, а сервис сам передает данные при изменении. Новый заказ в интернет-магазине — и вебхук отправляется на URL вашего сервера в реальном времени. Не нужно создать цикл опроса, не нужно тратить ресурсы на пустые ответы.

Если нужно получать уведомления о событиях мгновенно — настроить вебхук.
Если нужно забрать данные по расписанию или запросить конкретную информацию (например, список всех товаров из базы данных) — использовать API.

Какие события запускают вебхуки

Вот конкретные примеры событий, на которые часто настраивают вебхуки:

Новый заказ или изменение статуса доставки в интернет-магазине — вебхук передаёт данные в CRM или отправляет уведомление менеджеру.
Оплата через платежные системы — при получении подтверждения сервис отправляет webhook с информацией о транзакции.
Новая заявка с формой на сайте — вебхук сразу передает данные пользователя в систему аналитики или чат-боты в Telegram.
Создание новой задачи или обновление статуса в трекере — другие сервисы получают входящие уведомления и обновляют свои записи.
Новое письмо на почте, push от мессенджера, любой другой триггер — создание интеграции без ошибок и задержек.

Большинство современных сервисов — CRM-системы, платежные шлюзы, конструкторы сайта, чат-боты — поддерживают webhooks как инструменты уведомлений о событиях. Это стандартный способ передачи данных между системами в реальном времени. Безопасность при этом обеспечивают подписи и верификация — об этом подробнее дальше.

Пошаговая настройка вебхука на практике

Теперь разберём, как настроить вебхук на практике — от создания эндпоинта до получения первого уведомления. Алгоритм одинаков для любой платёжной системы, CRM или интернет-магазина.

Шаг 1. Создать URL, который принимает входящие запросы

Для работы вебхука необходим публичный URL — адрес в интернете, на который сервис-отправитель сможет отправить уведомления с данными о событии.

Чем можно пользоваться, чтобы настроить:

Специальные сервисы для тестирования — открываете сайт, сразу получаете готовый URL. Каждый входящий запрос отображается в реальном времени. Идеально, чтобы посмотреть, какую информацию отправляет сервис.
Инструменты туннелирования — пробрасывают ваш локальный сервер в интернет. Получаете публичный URL, и сервис-отправитель может передавать данные напрямую.

Шаг 2. Зарегистрировать URL в сервисе

Перейдите в личном кабинете в раздел API или «Интеграции». Нажмите «Добавить новый вебхук», вставьте URL из первого шага и выберите события — например, «Оплата успешна» или «Создание заказа». Сервис сохраняет адрес и начинает отправлять уведомления при каждом определенном событии.

Шаг 3. Отправить тестовый вебхук

Большинство сервисов дают кнопку «Отправить тестовый запрос» прямо из настроек. Нажмите её и проверьте: произошло ли событие, пришла ли информацию в теле запроса, какой статус вернул ваш сервер. Если ответ — 200 OK, настройка интеграции работает. Если произошло что-то другое, сервис часто запускает повторные попытки доставки, и начинаются дубли.

Шаг 4. Настройка сервера для обработки вебхуков

Когда вебхук приходит на ваш URL, сервер принимает данные и должен что-то с ними сделать. Есть два подхода в зависимости от вашего уровня.

Если вы разработчик: сервер извлекает информацию из тела запроса в формате JSON — например, о заказе или изменении статуса — и сохраняет её в базу данных. Безопасность обработки гарантирует механизм проверки подписи, о котором подробно рассказано в следующем разделе.

Если вы работаете без кода, готовые инструменты автоматизации берут все задачи на себя. Принцип работы простой — создаете сценарий, указываете триггер в виде вебхука, получаете URL и вставляете его в личном кабинете нужного сервиса. Дальше система сама принимает входящие запросы и передаёт данные туда, куда нужно — в CRM отдела продаж, таблицы или чат-боты. Вся настройка занимает 10–15 минут, и ни одной строчки кода писать не придётся.

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

Выводим сайты в ТОП-1 Яндекса

Продвигаем сайты в топ выдачи с помощью поведенческих факторов и уникальных технологий.

Попробовать бесплатно

Безопасность вебхуков и обработка ошибок

Безопасность вебхуков — тема, которую часто откладывают на потом. А потом происходит неприятное: кто-то отправляет поддельный POST-запрос на публичный URL обработчика, и система интернет-магазина помечает несуществующий заказ как оплаченный. Или сервер падает, платежные системы шлют повторные уведомления, и клиента списывают дважды. Разберём, как от этого защититься.

Верификация: проверка подписи

Любой вебхук приходит как обычный HTTP-запрос на адрес, который доступен из интернета. Это значит, что отправить данные на этот URL может кто угодно — не только реальные сервисы, но и злоумышленник. Способ защиты — проверка подписи с помощью секретного ключа.

Работает вебхук с подписью так: сервис берёт тело запроса в формате JSON, хеширует его алгоритмом с использованием секретного ключа, который известен только двум сторонам, и кладёт результат в заголовок. Приложение на принимающей стороне выполняет те же действия — берёт тело, хеширует тем же ключом — и сравнивает. Если подписи совпали, значит, данные пришли от настоящего отправителя и не были изменены по пути. Если нет — запрос нужно сразу отклонить с кодом 403.

Антипример: обработчик принимает любой входящий webhook без проверки подписи. Злоумышленник узнаёт URL сайта, формирует JSON с "status": "paid" и отправляет его напрямую. Система обрабатывает данные как настоящее событие — менеджер отдела продаж видит оплату и отправляет товар. Убыток налицо.

Повторная отправка и проблема дублей

Что происходит, если сервер вернул ошибку или не ответил вовремя? Большинство сервисов используют механизм retry — повторные попытки доставки уведомления. Типичная схема: первая повторная отправка через 30 секунд, вторая — через 5 минут, третья — через 10 минут. Некоторые API делают до 15–20 попыток в течение нескольких суток.

Проблема в том, что событие при этом каждый раз одно и то же. Если сервер принял вебхук, начал обработку, но не успел ответить 200 OK за отведенное время, сервис считает доставку неудачной и отправляет данные снова. Приложение обрабатывает заказ повторно — списание происходит дважды, уведомления о событиях дублируются, в базе данных появляются двойные записи.

Решение — уникальный идентификатор события (idempotency key). Каждый вебхук содержит поле вроде event_id или idempotency_key. Перед обработкой нужно проверить: если событие с таким идентификатором уже было обработано, просто вернуть ответ 200 OK и пропустить повторное выполнение. Храните обработанные идентификаторы в базе — этого достаточно для защиты от дублей.

Выводы: когда и зачем использовать вебхуки

Теперь, когда настройка и безопасность разобраны, остаётся один вопрос: а когда вебхук — действительно правильный выбор, а когда лучше использовать обычный API?

Когда вебхуки — то, что нужно

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

Получение уведомлений о событиях в платежной системе — оплата прошла, возврат произошел, подписка продлилась. Платежные системы сразу отправляют POST-запрос на указанный URL, и менеджер отдела продаж видит новый заказ в CRM через секунды.
Интеграции в реальном времени — сервис доставки отправляет изменение статуса заказа, GitHub отправляет данные о новом коммите, форма на сайте передаёт информацию о заявке. Каждый раз, когда произошло определенное событие, система сразу уведомляет все связанные сервисы.
Автоматизация отправки уведомлений и сообщений — чат-боты в Telegram, письма клиенту, push-уведомления. Вебхук отправляется, и приложение запускает нужное действие без участия человека.

Простой способ понять: если данные появляются непредсказуемо и нужно реагировать мгновенно — выберите webhooks.

Когда лучше использовать polling через API

Если задача — получить информацию по запросу в любой удобный момент (например, загрузить каталог интернет-магазина, выгрузить отчет из базы данных или синхронизировать справочники раз в 30 минут), то polling через API — более подходящий механизм. Вебхук тут не поможет: он срабатывает только когда что-то происходит, а не когда это нужно вам.

Чеклист готовности вебхука

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

Публичный URL работает по HTTPS — без SSL ни один серьезный сервис не станет передавать данные на ваш адрес.
Проверка подписи (HMAC или другие способы верификации) — каждый входящий HTTP-запрос проверяется на подлинность, чтобы обеспечить безопасность обработки данных пользователя.
Ответ 200 OK за 3–5 секунд — сервер принимает webhook, кладёт информацию в очередь и отвечает. Бизнес-логику выполняет фоновый процесс.
Идемпотентность — если один и тот же вебхук пришёл дважды (а такое случается), система обрабатывает его только один раз. Для этого используют уникальный идентификатор события из тела запроса в формате JSON.
Логирование — записывайте все входящие запросы с заголовками, телом и кодом ответа.
Мониторинг и алерты — настройте уведомления на случай, если сервер перестал отвечать или процент ошибок вырос.

Следующий шаг

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

Попробуйте настроить отправку вебхука из любого сервиса (хоть из Google Forms) на этот адрес и посмотрите, какие данные приходят. На всё уйдёт 5–10 минут.