Вебхуки: как получать данные без промедления и опросов API
Простыми словами объясняем, чем вебхуки отличаются от API, как их безопасно использовать и создавать на примере GitHub.
В сфере веб-разработки наряду с API распространилось понятие вебхук (англ. webhook). Рост популярности этого стандарта связан с тем, что всё больше действий в вебе можно описать в терминах событий. Триггерами, запускающими вебхук, могут служить, например, отправка кода в репозиторий или публикация комментария.
Вебхук – это механизм оповещения о происходящих в системе событиях посредством функций обратных вызовов. Когда случается интересующее клиента событие, сервер отправляет HTTP-запрос на URL-адрес, предоставленный клиентом для приема вебхуков.
Чем вебхуки отличаются от API?
В типичных API для получения информации от сервера его необходимо постоянно опрашивать. В случае вебхуков сервер как бы говорит клиенту: «Теперь тебе не придется названивать. Я сам позвоню, когда появится что-то новое».
То есть с помощью вебхука клиент «подписывается» на получение оповещений в заранее определенных случаях. Такой подход удобнее и для провайдера информации, и для клиента. При этом вебхуки используют HTTP, то есть не требуется добавления какой-то дополнительной инфраструктуры.
Вебхук делает HTTP-запрос к вашему приложению (чаще всего POST-запрос в JSON-формате), а интерпретация запроса уже зависит от принимающей стороны. Вебхуки — это своеобразные «обратные API» – интерфейс взаимодействия с запросом должен быть построен на стороне клиента.
У большинства API необходимо вначале отправить запрос, за которым последует ответ системы. В случае вебхука вы заранее настраиваете, при каких событиях сервер отправляет данные. Рассмотрим на примере.
В случае API приложение сервера предоставляет приложению клиента адреса, которые может вызывать приложение на стороне клиента. Например, для доски сообщений запросы к API могут выглядеть следующим образом:
POST /messages createNewMessage
GET /messages/{messageId} readMessage
POST /messages/{messageId}/comments postComment
GET /messages/{messageId}/comments/{commentsId} readComment
Для вебхуков ситуация обратная: уже приложение клиента предоставляет приложению сервера адреса для вызова. А приложение сервера в свою очередь использует эти URL, когда на стороне сервера происходит какое-либо интересующее клиента событие.
Допустим, мы хотим, чтобы сервер уведомлял приложение клиента при добавлении нового комментария. Всякий раз, когда новый комментарий публикуется в базе данных на стороне сервера, приложение сервера должно (после публикации комментария в базе данных) вызывать URL вебхука, чтобы клиент знал, что доступен новый комментарий.
Примеры использования вебхуков
Оглянувшись вокруг, мы увидим, что многие компании внедрили вебхуки в своей практике. Несколько примеров:
- Github позволяет настраивать вебхуки для отправки информации об обновлениях, действиях пользователей и других событиях.
- В приложениях на основе Twilio звонки, текстовые сообщения и реакции на них также поддерживаются с помощью вебхуков.
- Бесспорным королем вебхуков является сервис Zapier, представляющий собой экосистему для взаимодействия приложений между собой.
Поставщики данных могут предоставлять специальные панели для удобства указания ссылок, куда отправляются HTTP-запросы. Ниже представлена панель управления вебхуками сервиса Intercom.
Попробуйте свои силы
Лучший способ понять технологию применения вебхуков — это попробовать ее в деле. Давайте поэтапно рассмотрим процесс настройки и получения вебхука на реальном примере.
Даже если у вас нет приложения и соответствующих URL, можно попробовать технологию вебхуков в деле. Для таких задач создан ресурс webhook.site. Он генерирует уникальную ссылку для проверки входящих POST-запросов.
Скопируем сгенерированную ссылку, и, оставив страницу открытой, передадим URL провайдеру вебхука. Например, настроим вышеупомянутый вебхук в GitHub. Для этого перейдем в каком-либо из своих репозиториев в раздел Settings/Webhooks и нажмем кнопку Add webhook.
Заполнение открывшейся формы является процессом настройки вебхука. В поле Payload URL вставим запасенную ссылку с webhook.site. В качестве Content type выберем application/json. Далее отметим события, при которых GitHub будет отправлять запрос, например, комментарий коммита.
В конце списка нажимаем кнопку активации вебхука. Оставляем в репозитории комментарий к коммиту, чтобы протестировать механизм.
При этом GitHub в соответствии с вебхуком сразу же отправит POST-запрос на нашу ссылку. Вернувшись на страницу webhook.site, увидим, что в списке запросов добавился новый. В панели справа мы можем видеть детали запроса, заголовки и сам JSON-объект (для удобства чтения выберите пункт Format JSON).
Изучив JSON, вы заметите, что GitHub отправляет исчерпывающую информацию даже для такой простой операции, как комментарий коммита. Для сравнения в новой вкладке браузера перейдите по той же тестовой ссылке для приема запросов. Вы увидите, какую информацию дает «пустой» GET-запрос.
Аналогично можно протестировать другие интересные вам ресурсы. Например, подробное пособие есть у Slack. А Dropbox умеет высылать уведомления на универсальный идентификатор ресурса, когда пользователь вашего приложения вносит изменения в файл.
Отладка вебхуков
Вебхуки являются асинхронным методом, поэтому их отладка может оказаться довольно утомительной. К счастью, есть инструменты, упрощающие этот процесс:
- Инструмент RequestBin собирает запросы вебхуков и позволяет понять их назначение.
- Смоделировать запросы помогут cURL и Postman.
- Протестировать код на вашей машине можно на локальном сервере ngrok.
- Сервис httpresponder создаст точку сбора и реагирования на вебхуки.
Безопасность использования вебхуков
Если вебхуки доставляют данные в приложение по публичным URL, кто-то может перехватить эти ссылки и подменить ложными данными? Чтобы этого не случилось, вы должны предпринять ряд мер. То, с чего нужно начать – использовать протокол HTTPS. Вы можете пойти дальше и еще больше обезопасить соединение:
- Добавить в URL токены, действующие как уникальные идентификаторы
- Реализовать Basic Auth, что также широко поддерживается и легко сделать.
- Два приведенных решения отлично работают для предотвращения большинства атак. Их недостаток заключается в отправке аутентификационного токена. Третий вариант заключается в том, чтобы поставщик данных подписывал каждый запрос, а затем проверял подпись. Так, GitHub подписывает запросы в заголовке HTTP HMAC-ключом, а Facebook – c помощью алгоритма SHA-1.
Важные замечания
При использовании вебхуков нужно помнить о нескольких важных деталях.
После доставки запроса с данными вебхуки могут перестать отвечать. Это означает, что если в приложении произойдет ошибка, данные могут быть потеряны. Поэтому, чтобы подготовиться к возможным падениям приложения, разберитесь, как провайдер вебхука обрабатывает ответы.
Если на стороне провайдера события происходят часто, такая нагрузка может закончиться падением приложения (как в результате DDoS-атаки). Убедитесь, что клиентское приложение способно обработать ожидаемый масштаб запросов.
Хотя технически вебхуки могут использоваться для передачи массивов данных, рекомендуется использовать их лишь как сигнал изменения состояния. Как только уведомление получено, нужно вызывать безопасный интерфейс API для получения настоящей нагрузки. Такое разделение позволяет повысить масштабируемость и надежность систем обработки данных.