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

Введение

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

Webhooks также иногда называют «Обратными API» . В API клиентское приложение вызывает (потребляет) серверное приложение. Принимая во внимание, что в случае веб-хуков именно серверная сторона вызывает (потребляет) веб-хук (URL-адрес конечной точки, предоставляемый клиентским приложением), то есть это серверное приложение вызывает клиентскую сторону. применение.

Webhooks используют концепцию «реакции на события» (не звоните мне, я позвоню вам, если у меня будет что-то новое) , и, таким образом, избегают необходимости постоянного опроса приложения на стороне сервера приложением на стороне клиента. Таким образом, вместо того, чтобы клиентское приложение постоянно опрашивало серверное приложение для проверки новых событий, серверное приложение вызывает клиентское приложение (вызывая URL-адрес, предоставленный клиентом) каждый раз, когда на стороне сервера появляется что-то новое. сообщить клиенту.

Это основная концепция Webhook.

Таким образом, с помощью webhooks вы можете получать push-уведомления, когда на сервере происходят определенные события. Вам больше не нужно опрашивать API, чтобы узнать, произошли ли эти события. Вы можете просто «подписаться» на событие с помощью веб-крючков.

Итак, как именно выглядит webhook?

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

POST /messages                                     createNewMessage
GET  /messages/{messageId}                         readMessage
POST /messages/{messageId}/comments                postComment
GET  /messages/{messageId}/comments/{commentsId}   readComment

Эти URL открываются приложением на стороне сервера .

Таким образом, если клиентское приложение хочет опубликовать новое сообщение на сервере, клиентское приложение вызывает (использует) POST / messages

Аналогично, если клиентское приложение хочет прочитать комментарий, опубликованный к определенному сообщению на сервере, клиентское приложение вызывает (потребляет) GET / messages / {messageId} / comments / {commentsId}

Обратите внимание, что сообщения и комментарии создаются и хранятся в базе данных сервера и считываются из базы данных сервера с использованием предоставленных сервером API (конечных URL-адресов).

В случае Webhooks, это приложение на стороне клиента предоставляет приложению на стороне сервера URL для вызова, а приложение на стороне сервера вызывает (использует) этот URL, когда происходит какое-либо соответствующее событие на стороне сервера. Таким образом, webhook — это просто URL-адрес конечной точки, предоставляемый клиентским приложением для серверного приложения. В нашем простом примере на доске объявлений это может выглядеть так.

{  
“newCommentWebhook” :  “https://clientdomain.com/webhook/newcomment" 
}

Таким образом, webhook — это не что иное, как простой URL-адрес конечной точки на стороне клиента. Этот конечный URL-адрес должен быть передан приложением на стороне клиента приложению на стороне сервера в некоторый момент перед вызовом webhook на стороне сервера.

Допустим, мы хотим, чтобы приложение на стороне сервера уведомляло приложение на стороне клиента при каждом добавлении нового комментария к определенному сообщению. В этом случае всякий раз, когда новый комментарий публикуется в базе данных на стороне сервера, приложение на стороне сервера должно (после публикации комментария в базе данных) вызывать вышеуказанный URL-адрес webhook, чтобы клиент знал, что доступен новый комментарий. Таким образом, используя webhooks, серверная сторона может уведомить клиентскую сторону о соответствующем событии (то есть был опубликован новый комментарий).

С точки зрения реализации, серверное приложение должно спроектировать свои конечные точки API так, чтобы существовал некоторый параметр-заполнитель, который позволяет клиентским приложениям передавать им URL-адрес webhook. Это может быть сделано с помощью «тела запроса» API на стороне сервера, имеющего параметр для URL-адресов веб-хука.

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

Использование веб-крючков для уведомлений и доставки полезных данных

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

Как только уведомление об изменении состояния получено, отдельные клиентские приложения могут вызывать безопасный интерфейс API для получения фактической полезной нагрузки. Такое разделение интересов позволяет повысить масштабируемость и надежность общей интеграции API.

Ресурсы

Следующий сайт позволяет вам протестировать концепцию веб-хука https://webhook.site/ . Он генерирует уникальный тестовый URL-адрес webhook, который может вызываться вашим приложением для проверки функции обратного вызова (уведомления) webhook.