Вебхук — это способ автоматически сообщить другой системе о произошедшем событии через HTTP-запрос. Когда в сервисе меняется нужный объект, он отправляет данные на заранее указанный URL, а принимающая сторона обрабатывает сообщение и запускает действие.
Механизм используют для синхронизации заказов, платежей, лидов, статусов доставки, рассылок и других процессов. Получателю не приходится постоянно спрашивать источник об изменениях: информация приходит сразу после события или с небольшой технической задержкой.
Как работает вебхук
Система-получатель предоставляет конечный адрес, доступный по защищённому соединению. В системе-источнике выбирают события и регистрируют этот URL. Когда событие происходит, источник формирует запрос, обычно методом POST, и передаёт полезную нагрузку в согласованном формате, часто JSON.
Получатель проверяет запрос, сохраняет данные и возвращает код успешного ответа. Если подтверждение не пришло, источник может повторить доставку по собственным правилам. Важно заранее изучить документацию конкретного сервиса: названия полей, подписи, количество повторов и допустимое время ответа различаются.
Отличие вебхука от API-запроса
При обычном опросе API приложение само периодически запрашивает состояние: появился ли новый заказ, прошла ли оплата, изменился ли контакт. Такой подход создаёт лишние обращения и всё равно обнаруживает событие только во время следующей проверки. Вебхук меняет направление: источник отправляет уведомление по факту изменения.
Механизмы дополняют друг друга. Вебхук быстро сообщает, что случилось, а API может потребоваться для получения полной карточки, проверки текущего состояния или восстановления пропущенных данных. Для критичных процессов полезна периодическая сверка, потому что ни один канал доставки нельзя считать абсолютно безошибочным.
Где применяют вебхуки
Интернет-магазин получает уведомление от платёжной системы и меняет статус заказа. CRM принимает заявку с формы, служба доставки сообщает о перемещении отправления, а сервис рассылок передаёт событие доставки, открытия или отписки. Внутренние системы используют тот же принцип для оповещений и автоматизации.
- создание и обновление лидов;
- подтверждение платежей и возвратов;
- синхронизация заказов и остатков;
- уведомления о статусе сообщений;
- запуск сценариев в интеграционных платформах;
- контроль событий безопасности.
Для каждого сценария нужно определить, какое событие считается источником истины и что произойдёт при повторной доставке.
Надёжность и безопасность
Адрес обработчика должен использовать HTTPS. Получатель проверяет подпись или секрет, если источник поддерживает такой механизм, ограничивает размер тела запроса и не доверяет входным полям без валидации. Секреты нельзя размещать в публичном коде или журнале.
Обработчик отвечает быстро, а тяжёлую работу переносит в очередь. Это уменьшает риск тайм-аута и повторной доставки. Каждому событию присваивают идентификатор и делают обработку идемпотентной: повтор того же уведомления не должен второй раз списывать деньги, создавать заказ или отправлять письмо. Ошибки и попытки повторов фиксируют для расследования.
Настройка и проверка
Сначала разработчик изучает перечень событий и пример полезной нагрузки. Затем создаёт тестовый endpoint, регистрирует его в сервисе и инициирует событие в тестовой среде. Проверяют заголовки, формат, подпись, коды ответа, повторную отправку и поведение при недоступности получателя.
- Определить события и обязательные поля.
- Создать защищённый URL обработчика.
- Проверить подлинность запроса и структуру данных.
- Сохранить идентификатор события до выполнения действия.
- Вернуть успешный ответ и обработать задачу асинхронно.
- Настроить мониторинг ошибок и сверку состояния.
После запуска документацию и секреты пересматривают при изменении интеграции.
Технологию и связанные с ней требования важно учитывать при разработки сайта от Saygona.
Комментарий экспертаНадёжная интеграция начинается с предположения, что одно событие может прийти дважды, с задержкой или не по порядку. Идемпотентность, проверка подписи, журнал идентификаторов и периодическая сверка через API защищают бизнес-процесс лучше, чем надежда на идеальную доставку.
Вопросы и ответы: Вебхук
Он отправляет уведомление о событии и связанные данные в формате, который определяет сервис-источник. Часто полезная нагрузка передаётся как JSON.
Он сообщает об изменении по факту события, поэтому уменьшает число пустых запросов и обычно сокращает задержку между изменением и реакцией системы.
Источник повторяет доставку, если не получил ожидаемый ответ. Обработчик должен узнавать идентификатор события и не выполнять необратимое действие дважды.
Используют HTTPS и предусмотренную сервисом подпись или секрет. Алгоритм проверки берут из официальной документации конкретного поставщика.
