Webhook url что это

Реализация вебхуков на примере взаимодействия сторонних сервисов с онлайн-кассами

Я попросил нашу команду маркетинга нарисовать иллюстрацию и долго объяснял, что такое вебхуки

Не так давно передо мной встала задача реализовать работу вебхуков в Личном кабинете владельца кассы компании Дримкас. Как оказалось, в сети практически нет описания и туториалов, как это сделать. Я расскажу, как мы это реализовали без тяжелых кронов по БД.

Статья будет полезна для middle node.js-разработчиков.

Где используем вебхуки

Для понимания специфики, придется начать издалека.

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

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

Вебхуки нам понадобились, когда мы подключали к Кабинету интернет-магазины. Для онлайн-торговли тоже нужна касса, только бумажный чек не печатается. Мы решили создать для них инструмент, чтобы они могли из обычного json-а с данными о покупке записать данные о продаже в ФН и передать их в ОФД.

Так как операция фискализации может затянуться на длительное время, превышающее обычный HTTP запрос, нам потребовалось дать возможность узнавать статус этого чека. Каждый раз стучаться в Кабинет за статусом чека не выгодно ни нам, ни Интернет магазину. А с вебхуками убиваем сразу двух зайцев: Кабинет делает запрос только один раз, а интернет-магазин получит чек, как только он будет готов.

Когда мы начали их внедрять, решили дать доступ к этому функционалу сервисам интеграторов. С их помощью сторонние сервисы, которые подключены к Кабинету, получают уведомления о продажах, открытии/закрытии смен, создании и редактировании товаров, внесении и изъятии денег. Мы не остановились до сих пор, и все важные события мы сразу переводим на вебхуки.

Наши требования к вебхукам

Текущий стэк бэкенда

Мы пишем на node.js. В качестве веб фреймворка выбран koa. У нас две базы данных. Postrges с sequelize, где хранятся сильно связанные данные, например, кассы и пользователи. Для хранения несвязанных и неизменяемых данных — чеков, смен — мы используем MongoDB. Ещё повсеместно используются очереди на rabbitMQ, для сглаживания скачкообразных нагрузок. Плюс redis для кэша.

Реализация вебхуков

Определяем события для вызова вебхуков

Для начала определим места, где хотим вызывать вебхуки. На уровне модели мы можем пользоваться хуками в mongoose и в большинстве случаев в sequelize.

Исторически так сложилось, что в нашей sequelize-модели нельзя создать товар сразу с данными. Мы создаем пустой товар и сразу его изменяем, поэтому пришлось руками во всех контроллерах добавить обработчики вызовов вебхуков.

Когда нет такой проблемы, всё достаточно просто. Пример из модели mongoose:

Подписки на события

Чтобы определить понятие подписки на определенные события, мы используем битовые маски.

В бэкэнде мы храним всю информацию о типах событий одним числом, а фронту отправляем готовый json объект:

Чтобы упаковать число в json и извлечь его обратно, мы создаем виртуальные атрибуты в sequelize. В них устанавливаем геттеры и сеттеры. Виртуальные поля вычисляются на лету, изменяют на поля в таблице, но при этом не хранятся БД.

CRUD для управления вебхуками

Пользователь управляет вебхуками из веб-интерфейса или через API. Поэтому нам нужны стандартные CRUD для этой модели.

Подготовка к вызовам

Мы не вызываем вебхуки в статическом методе класса Webhook — это позволяет сберечь ресурсы основного сайта. Это работа воркеров — делать фоновые задачи, не мешая работе с REST-API.

Когда на сайте генерируется событие, мы оповещаем воркеров об этом:

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

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

Вызовы и повторные вызовы вебхуков

У нас в стеке используется очереди сообщений. Мы выбрали 5 временных промежутков, и на каждый создали очередь. Если вызов не удался при первой попытке, вебхук переходит в следующую очередь. Когда воркер получает на вход задачу, он откладывает его выполнение на требуемое количество времени от 0 миллисекунд до суток. Через 24 часа мы вызываем вебхук в последний раз и удаляем.

Пример вебхука, который не могут принять в течение суток.

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

Еще 4 факта

Источник

Вебхуки

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

Что такое вебхук?

Непосредственно сам вебхук содержит описание изменения (тип объекта и ссылку на изменившийся объект), которое отправляется на указанный url. Пример тела запроса вебхука:

В чем разница между АПИ и вебхуками

Есть 2 подхода для получения сведений об изменениях в системе: опрос через АПИ (polling) и подписка на вебхуки. Опрос через АПИ предполагает циклические запросы, чтобы получить изменения. Подписка на вебхуки предполагает получение уведомления об изменении в системе. Можно провести следующую аналогию. Предположим вы заказали товар, но его не оказалось в наличии, поэтому вы каждый день звоните в магазин, чтобы узнать о появлении товара, это похоже на опрос через АПИ. Но вы можете просто попросить менеджера в магазине позвонить вам по указанному номеру телефона, когда товар появится, это подписка на вебхуки. Очевидно, что подписка на вебхуки эффективнее и проще, так как гарантируется оперативное получение изменений в системе и меньшая нагрузка на клиентское приложение.

Когда нужно использовать АПИ, а когда вебхук

Несмотря на преимущество использования вебхуков, важно понимать, что подписка на вебхуки это всего лишь форма уведомления об изменениях в системе. Действия с сущностями (CRUD) необходимо выполнять с помощью АПИ.

Возможные сценарии, когда подписка на вебхуки выглядит предпочтительнее опросов через АПИ:

Как использовать вебхуки через JSON API

Вебхуки в JSON API

Работа с вебхуками в МоемСкладе возможна только через JSON API. Методы работы с вебхуками позволяют создать, удалить, обновить, получить и отключить вебхуки.

Ключевыми признаками вебхука являются адрес отправки (url), тип сущности (entityType) и тип события (action). Пара признаков (entityType и action) должна быть уникальной, т.е. не может повторяться в других вебхуках. Существуют следующие типы событий (action):

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

Рассмотрим методы работы с вебхуками. Для создания вебхука достаточно указать url, entityType и action, как в примере ниже

В ответ должен придти json, содержащий описание вебхука

Как и в других запросах сущностей JSON API другие действия над вебхуками возможны только при указании идентификатора. В полученном json поле id. Пример получения вебхука по идентификатору.

У вебхука можно изменить поля, указанные при создании, а также включить/отключить его. Для этого выполняется PUT запрос с указанием идентификатора. Пример запроса с изменением события

Пример запроса с отключением вебхука.

Удаление вебхука выполняется по аналогии, но только используется метод DELETE.

Получить все вебхуки можно с помощью типичного GET запроса.

В ответ придет коллекция вебхуков.

Ограничения при работе с вебхуками

При работе с вебхуками есть ряд важных замечаний:

Отправка вебхука в клиентское приложение

МойСклад отправляет вебхук в клиентское приложение с помощью метода POST, указывая заголовок User-Agent со значением MoySklad webhook touch agent 1.0 (/https://www.moysklad.ru).

При отправке уведомления вебхука, МойСклад ожидает ответ от клиентского приложения со статусом 200 или 204, чтобы считать уведомление доставленным. При невалидном ответе от клиентского приложения наша система осуществляет еще 3 попытки отправки. Данные попытки осуществляются последовательно, без таймаутов между ними. Если все попытки закончились неудачно, то данное уведомление считается неотправленным и в дальнейшем удаляется, в клиентское приложение оно отправлено не будет, т.к. проблема на стороне клиентского приложения.

Как проверить, что вебхук работает?

Источник

База знаний

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

Этот механизм удобно использовать для интеграции с внешней системой (например CRM).

Настройка Webhook

Для настройки вебхука нужно зайти в профиль нужного аккаунта LeadBack и найти подраздел API. В поле URL-адрес обработчика указать адрес куда будут отправляться события.

Настройка адреса URL-обработчика для Webhook

Обратите внимание, чтобы настройки вебхук сохранились, адрес вы должны указать действующий адрес URL-обработчика. В момент сохранения, адрес проверяется на доступность (отправляется тестовый http-запрос). Если ваш обработчик вернет http-статус отличный от 200, настройки не будут сохранены.

Безопасность при использовании Webhook

Чтобы вы могли однозначно понимать что запрос на обработчик пришел от Leadback, используйте секретный параметр в URL (пример URL-обработчика с секретным параметром: https://myserver.com/webhook/leaback.php?key=WsETKhVTeNpiF4uNy2KfDYjMy). В коде обработчика вы будете проверять параметр key на соответствие заданному вами значению и если значение верное, то запрос на обработчик пришел от LeadBack.

Для обеспечения дополнительной безопастности (от перехвата данных) мы рекомендуем использовать https адрес (для этого у вас на сервере должен быть настроен валидный SSL-сертификат для домена).

Типы передаваемых событий

Структура данных

Для всех событий данные передаются в виде JSON объекта методом POST в поле payload. Ниже показан пример получения данных для php:

Для всех событий JSON-объект имеет единую структуру с 2 полями данных:

Новый обратный звонок

Событие срабатывает перед запуском дозвона (event_type=pre_call) и когда был принят или пропущен обратный звонок с сайта (event_type=call).

В данных события доступны следующие поля:

Информация о источнике звонка visit_data имеет следующие данные (поля для visit_data идентичны для всех типов событий):

Пример JSON данных для обратного звонка:

Новый диалог в чате с оператором

Отправляется когда завершится диалог в чате с вашим онлайн оператором.

В данных события доступны следующие поля:

Данные оператора в поле operator:

История переписки в поле chat_log это массив объектов с полями:

Поля visit_data и profile_data аналогичны как для события новый обратный звонок.

Пример JSON данных диалога с оператором:

Новый диалог в чате с ботом

Отправляется когда завершится диалог в чате с ботом.

В данных события доступны следующие поля:

История переписки в поле chat_log это массив объектов с полями:

Поля visit_data и profile_data аналогичны как для события новый обратный звонок.

Пример JSON данных диалога с ботом:

Проверка вебхук адреса

Тестовый запрос. Отправляется во время сохранения адреса webhook адреса, для проверки его доступности.

Источник

обзор webHooks ASP.NET

WebHooks представляет собой легкий шаблон HTTP, обеспечивающий простую модель паб/суб для проводки web-aIS и сервисов SaaS. Когда событие происходит в службе, уведомление отправляется в виде запроса HTTP POST зарегистрированным абонентам. Запрос POST содержит информацию о событии, которая позволяет получателю действовать соответствующим образом.

Из-за своей простоты, WebHooks уже подвергаются большое количество услуг, включая Dropbox, GitHub, Bitbucket, MailChimp, PayPal, Slack, Полоса, Trello, и многое другое. Например, WebHook может указать, что файл изменился в Dropbox,или изменение кода было зафиксировано в GitHub, или платеж был инициирован в PayPal, или карта была создана в Trello. Возможности безграничны!

Корпорация Майкрософт ASP.NET WebHooks упрощает отправку и получение WebHooks как части приложения ASP.NET:

Что касается принимающей стороны, то она обеспечивает общую модель для приема и обработки WebHooks от любого числа поставщиков WebHook. Он выходит из коробки с поддержкой Dropbox, GitHub, Bitbucket, MailChimp, PayPal, Pusher, Salesforce, Slack, Stripe, Trello,WordPress и Zendesk, но это легко добавить поддержку для более.

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

Эти две части могут быть использованы вместе или друг от друга в зависимости от вашего сценария. Если вам нужно только получать WebHooks от других служб, то вы можете использовать только часть приемника; если вы только хотите разоблачить WebHooks для других потреблять, то вы можете сделать именно это.

Код нацелен ASP.NET Web API 2 и ASP.NET MVC 5 и доступен в качестве OSS на GitHub.

Обзор WebHooks

WebHooks — это шаблон, который означает, что он изменяет, как он используется от службы к службе, но основная идея та же. Вы можете думать о WebHooks как простой паб / суб-модель, где пользователь может подписаться на события, происходящие в другом месте. Уведомления о событии распространяются как запросы HTTP POST, содержащие информацию о самом событии.

Обычно запрос HTTP POST содержит данные об объекте JSON или HTML-формы, определенные отправителем WebHook, включая информацию о событии, вызывающую срабатывание WebHook. Например, тело запроса WebHook POST от GitHub выглядит следующим образом в результате открытия новой проблемы в определенном репозитории:

Чтобы убедиться, что WebHook действительно от предполагаемого отправителя, post запрос защищен в некотором роде, а затем проверить приемник. Например, GitHub WebHooks включает в себя заголовок X-Hub-Signature HTTP с хэшом органа запроса, который проверяется реализацией получателя, так что вам не придется беспокоиться об этом.

Поток WebHook обычно идет что-то вроде этого:

Отправитель WebHook предоставляет события, на которые клиент может подписаться. События описывают наблюдаемые изменения в системе, например, что был вставлен новый элемент данных, что процесс завершен, или что-то еще.

Приемник WebHook подписывается, регистрируя WebHook, состоящий из четырех вещей:

URI, где уведомление о событии должно быть размещено в виде запроса HTTP POST;

Набор фильтров, описывающих конкретные события, для которых webHook должен быть уволен;

Секретный ключ, который используется для подписания запроса HTTP POST;

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

Как только событие происходит, соответствующие регистрации WebHook найдены и http POST запросы представлены. Как правило, генерация запросов HTTP POST повторно повторяется несколько раз, если по какой-то причине получатель не отвечает или запрос HTTP POST приводит к ответу на ошибку.

Конвейер обработки WebHooks

Конвейер обработки ASP.NET WebHooks для входящих WebHooks выглядит следующим образом:

Двумя ключевыми концепциями здесь являются приемники и обработчики:

Получатели несут ответственность за обработку конкретного вкуса WebHook от данного отправителя и для обеспечения проверки безопасности, чтобы убедиться, что запрос WebHook действительно от предполагаемого отправителя.

Обработчики, как правило, где пользовательский код работает обработки конкретного WebHook.

В следующих узлах эти понятия описаны более подробно.

Источник

Вебхук

Вебхук — это способ оповещения клиента о произошедшем в системе событии с помощью пользовательских обратных вызовов по HTTP.

Это термин из мира WEBа и программирования. Вебхук запускается, когда на вашем сайте, в CRM, чат-боте или иной системе происходит какое-то событие. Например, человек написал комментарий или в товароучетную систему добавили новый товар. Когда происходит такое событие, сервер создает HTTP-вызов и отправляет его на адрес, указанный клиентом для получения вебхуков. Клиент вовремя получает свежие данные — клиент доволен.

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

Зачем нужен вебхук, если есть API

Большинство API работает по принципу «Спроси меня и я отвечу». То есть для получения свежих данных, программному клиенту нужно постоянно отправлять запросы на сервер. Вебхуки работают иначе. Они как бы говорят: «Дружище, больше не нужно названивать. Если произойдет что-то для тебя важное, я сам сообщу». Схема запроса обратной связи по API. Программный клиент регулярно опрашивает сервер о наличии изменений. Если их нет, сервер дает отрицательный ответ. Если есть — оповещает об изменениях

Если простыми словами, вебхук — как бы подписка на обновления для определенных событий. Сервер будет оповещать клиента только о тех изменениях, которые ему по-настоящему важны. Он сам сообщит об этих событиях при настройке вебхука.

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

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

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

Вебхук работает в обратном порядке: URLы для отправки запроса формируется клиентом. А сервер, если на его стороне происходит важное для пользователя событие, использует эти URLы для отправки оповещения программному клиенту.

Представим, что пользователь хочет получать уведомления всякий раз, когда на его площадке появляется новое сообщение. Он создает необходимый интерфейс и настраивает вебхуки. Затем:

Как выглядит вебхук

По сути, вебхук — это программный код. Обычно он состоит из двух частей — переменной и самих данных. Например, как здесь. «First name» — это переменная, а «Anton» — это данные, которые передаются с помощью вебхука, которые постоянно меняются и подставляются системой. Количество переменных определяется софтом, на события в котором реагирует вебхук

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

Как используют вебхуки на практике

Сегодня вебхуки используются повсеместно. Вот несколько примеров на скорую руку:

Чтобы упростить работу с вебхуками, поставщики данных предоставляют пользователям готовые интерфейсные панели. На них можно создать новый вебхук, указать URL, на который будет отправлен вызов, выбрать событие и передаваемые параметры. Пользователю не нужно возиться с кодом — он заполняет простую форму, а за программную часть работы отвечает поставщик данных. Панель для создания и управления вебхуками от сервиса Callibri. Пользователь указывает адрес для отправки запроса, задает событие и его параметры. А все остальное делает сам сервис

Создаем тестовый вебхук

Кажется, что работать с вебхуками, при наличии программной панели от поставщика данных, просто. Перейдем от теории к практике — посмотрим, как это работает на примере.

Чтобы создать тестовый вебхук, не нужен свой сайт или приложение. Проверить работоспособность входящего запроса можно с помощью специального сервиса — Webhook.site. Он генерирует для вас тестовый урл, который можно использовать для отправки POST-запроса и проверки его содержимого на этом же сайте. Показываем, как это работает. Для проверки будем использовать свой репозиторий на Github.

Если вы пользуетесь сервисом, который дает возможность отправлять уведомления с помощью вебхуков, протестируйте его похожим образом. Например, если используете Dropbox, можно протестировать отправку уведомлений для события «внесение изменения в файл».

Помощь в отладке вебхуков

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

Безопасно ли пользоваться вебхуками

Обычно механизм использования вебхуков предусматривает доставку данных программному клиенту через публичные адреса URL. Это небезопасно: любой может перехватить эти адреса и подменить передаваемые данные в своих корыстных целях. Но этого можно избежать. Есть несколько способов:

О чем нужно помнить, если используешь вебхуки

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

Приложение может не выдержать нагрузку. В зависимости от вида вашей деятельности и настроенных триггеров, события на стороне сервера могут происходить слишком часто. Чем больше триггеров для отправки вебхука вы задаете, тем чаще программный клиент будет получать POST-запросы. Убедитесь, что ваше приложение готово к получению запрашиваемого объема данных. Если на сервере возникнет высокая активность, клиентское приложение может не выдержать нагрузки. Так бывает, например, при DDoS-атаках.

Не стоит передавать через вебхуки данные. Технически технология вебхук позволяет передавать программному клиенту объемные массивы данных. Но делать этого не стоит. Используйте вебхуки лишь для уведомления об изменении состояния на сервере. А когда сигнал получен — вызывайте API,запрашивайте данные и получайте настоящую нагрузку. Такой способ позволяет надежнее обрабатывать данные и не перегружать систему.

Источник