Webhook (вебхук) — это способ, которым один сервис сам сообщает другому о событии, отправляя HTTP-запрос на заранее заданный адрес. Не вы спрашиваете «что нового?», а сервис присылает уведомление, как только что-то произошло.
Типичный случай: покупатель оплатил заказ, платёжная система отправляет на ваш сайт запрос с данными платежа, а сайт отмечает заказ оплаченным и шлёт письмо. Так же работают уведомления из CRM, форм, мессенджеров, GitHub (событие push запускает сборку).
Вебхук — противоположность опроса. При опросе ваша система раз в минуту обращается к API с вопросом «есть новости?» и тратит запросы впустую. Вебхук приходит один раз и только по делу. В теле запроса обычно лежат данные события в формате JSON.
Как подключить вебхук
- Создайте на своём сервере адрес, который принимает POST-запросы.
- В настройках внешнего сервиса укажите этот URL и выберите события.
- Проверьте подпись запроса, чтобы убедиться, что он пришёл от нужного сервиса.
- Сразу верните ответ 200 и обработайте данные в фоне.
- Сохраняйте уникальный номер события, чтобы не обработать его дважды.
Типичные ошибки
- Не проверяют подпись, и любой может отправить на адрес поддельное «оплачено».
- Долго обрабатывают данные до ответа, сервис считает доставку неудачной и шлёт запрос повторно.
- Не учитывают повторы и получают дубли заказов.
- Используют адрес без HTTPS.
Чем отличается от API
В REST API инициатор вы: вы делаете запрос и получаете ответ. В вебхуке инициатор внешний сервис, а ваш адрес только принимает входящее. Часто их используют вместе.
Частый вопрос
Что делать, если вебхук не пришёл? Проверьте журнал доставки в личном кабинете сервиса: там видно код ответа вашего сервера. Затем убедитесь, что адрес доступен снаружи, а не только на локальной машине. Для надёжности дополнительно сверяйте данные через API.