Web hook что это
Реализация вебхуков на примере взаимодействия сторонних сервисов с онлайн-кассами
Я попросил нашу команду маркетинга нарисовать иллюстрацию и долго объяснял, что такое вебхуки
Не так давно передо мной встала задача реализовать работу вебхуков в Личном кабинете владельца кассы компании Дримкас. Как оказалось, в сети практически нет описания и туториалов, как это сделать. Я расскажу, как мы это реализовали без тяжелых кронов по БД.
Статья будет полезна для 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 факта
Вебхуки: как получать данные без промедления и опросов API
Leo Matyushkin
В сфере веб-разработки наряду с API распространилось понятие вебхук (англ. webhook). Рост популярности этого стандарта связан с тем, что всё больше действий в вебе можно описать в терминах событий. Триггерами, запускающими вебхук, могут служить, например, отправка кода в репозиторий или публикация комментария.
Вебхук – это механизм оповещения о происходящих в системе событиях посредством функций обратных вызовов. Когда случается интересующее клиента событие, сервер отправляет HTTP-запрос на URL-адрес, предоставленный клиентом для приема вебхуков.
Чем вебхуки отличаются от API?
В типичных API для получения информации от сервера его необходимо постоянно опрашивать. В случае вебхуков сервер как бы говорит клиенту: «Теперь тебе не придется названивать. Я сам позвоню, когда появится что-то новое».
То есть с помощью вебхука клиент «подписывается» на получение оповещений в заранее определенных случаях. Такой подход удобнее и для провайдера информации, и для клиента. При этом вебхуки используют HTTP, то есть не требуется добавления какой-то дополнительной инфраструктуры.
Вебхук делает HTTP-запрос к вашему приложению (чаще всего POST-запрос в JSON-формате), а интерпретация запроса уже зависит от принимающей стороны. Вебхуки — это своеобразные «обратные API» – интерфейс взаимодействия с запросом должен быть построен на стороне клиента.
У большинства API необходимо вначале отправить запрос, за которым последует ответ системы. В случае вебхука вы заранее настраиваете, при каких событиях сервер отправляет данные. Рассмотрим на примере.
В случае API приложение сервера предоставляет приложению клиента адреса, которые может вызывать приложение на стороне клиента. Например, для доски сообщений запросы к API могут выглядеть следующим образом:
Для вебхуков ситуация обратная: уже приложение клиента предоставляет приложению сервера адреса для вызова. А приложение сервера в свою очередь использует эти URL, когда на стороне сервера происходит какое-либо интересующее клиента событие.
Допустим, мы хотим, чтобы сервер уведомлял приложение клиента при добавлении нового комментария. Всякий раз, когда новый комментарий публикуется в базе данных на стороне сервера, приложение сервера должно (после публикации комментария в базе данных) вызывать URL вебхука, чтобы клиент знал, что доступен новый комментарий.
Примеры использования вебхуков
Оглянувшись вокруг, мы увидим, что многие компании внедрили вебхуки в своей практике. Несколько примеров:
Поставщики данных могут предоставлять специальные панели для удобства указания ссылок, куда отправляются 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 умеет высылать уведомления на универсальный идентификатор ресурса, когда пользователь вашего приложения вносит изменения в файл.
Отладка вебхуков
Вебхуки являются асинхронным методом, поэтому их отладка может оказаться довольно утомительной. К счастью, есть инструменты, упрощающие этот процесс:
Безопасность использования вебхуков
Если вебхуки доставляют данные в приложение по публичным URL, кто-то может перехватить эти ссылки и подменить ложными данными? Чтобы этого не случилось, вы должны предпринять ряд мер. То, с чего нужно начать – использовать протокол HTTPS. Вы можете пойти дальше и еще больше обезопасить соединение:
Важные замечания
При использовании вебхуков нужно помнить о нескольких важных деталях.
После доставки запроса с данными вебхуки могут перестать отвечать. Это означает, что если в приложении произойдет ошибка, данные могут быть потеряны. Поэтому, чтобы подготовиться к возможным падениям приложения, разберитесь, как провайдер вебхука обрабатывает ответы.
Если на стороне провайдера события происходят часто, такая нагрузка может закончиться падением приложения (как в результате DDoS-атаки). Убедитесь, что клиентское приложение способно обработать ожидаемый масштаб запросов.
Хотя технически вебхуки могут использоваться для передачи массивов данных, рекомендуется использовать их лишь как сигнал изменения состояния. Как только уведомление получено, нужно вызывать безопасный интерфейс API для получения настоящей нагрузки. Такое разделение позволяет повысить масштабируемость и надежность систем обработки данных.
Результаты поиска « код вставки виджета »
Описание API
Инструменты
Методы API — Webhooks
Примеры
Методы API — Пользователи
Методы API — События
Методы API — Оплаты от юрлиц
Методы API — Заказы
Методы API — Словари
Методы API — Организации
Коллбэки и webhooks
Что такое webhook
Webhook — механизм получения уведомлений об определённых событиях на TimePad (в основном о действиях пользователей) на свой собственный сайт.
Например, на TimePad есть webhook, который позволяет отслеживать изменения статусов регистрации пользователей. Он вызывается каждый раз при изменении любого билета вашей организации. По сути происходит вот что: данные регистрации кладутся в JSON и отправляются на URL, указаный в настройках организации.
Как настроить webhook
Для использования достаточно прописать в настройках организации URL, на который будет отправляться POST-запрос.
В поле Ссылка для уведомления нужно оставить адрес, к которому TimePad будет обращаться в случае смены статусов билетов, а в поле Секретная фраза — ключ, которым будет подписано сообщение от TimePad. И не забудьте нажать «Сохранить».
После этого при любой смене статуса билета в вашей организации — например, при регистрации или оплате — будет выполняться POST-запрос на адрес, который вы указали в настройках.
Как прочитать webhook
Пример чтения webhook’а в PHP
Типы вебхуков
Сейчас существует 3 типа вебхуков:
Использование вебхуков по изменению статуса заказа и билета
Вебхуки по заказу и билетам связаны между собой. При любом измении заказа посылается вебхук по заказу и вебхуки по каждому из билетов в заказе.
Данные вебхуки посылаются в случаях:
Содержание JSON запроса для хука изменения статусов заказа
Структура аналогична ответу API по заказам OAuth2. Пример такого json’a:
Содержание JSON запроса для хука изменения статусов билетов
Список возможных статусов билетов
Поля status:name / status_raw в запросе могут содержать следующие значения (в скобках указаны соответствующие значения поля status:title / status )
Как отвечать на webhook
В таких случаях запрос будет отправлен на этот же адрес с теми же данными через час. Если эта попытка тоже не удалась, следующая состоится через сутки. После этого запрос будет удалён из очереди, даже если доставка так и не состоялась. Следите за своими серверами 😉
Проектирование системы, принимающей вебхуки
Разрабатывая систему, принимающую вебхуки, лучше снадбите её логами — какие вебхуки приходили.
Обязательно предусмотрите у себя следующие свойства вебхуков (кстати, все это относится к вебхукам абсолютно любых систем):
Порядок прихода вебхуков не обязательно хронологический
Вебхуки отправляются в множество потоков. Совершенно не исключен тот факт, что какой-то из потоков отправит более поздний вебхук быстрее, чем соседий поток — более ранний. Если нарушение хронологии может вам что-то сильно сломать — проверяйте дату хука (поле hook_generated_at ), сравнивайте её с датой последнего хука по той же сущности, который вы приняли.
Вебхук может не прийти вовсе
Когда отправитель вебхука видит, что отправленный запрос не завершился корректно (HTTP статусом 200 OK), он его обычно переотправляет (еще одно место где может сбиться хронология). Вторая отправка чаще всего завершается успехом.
Один и тот же вебхук может прийти несколько раз
Достаточно часто бывает так, что принимающая сторона на самом деле обработала вебхук и ответила корректным статусом, но отправитель этого ответа не дождался или интерпретировал его неверно (например, при проблемах сети).
В этом случае отправитель сделает повторную попытку отправки вебхука и принимающая сторона будет обязана обработать его корректно – т.е. проигнорировать, но отправить ответ HTTP 200 OK. Вы можете проверять GUID вебхука (поле hook_guid ).
При отправке вебхука есть таймаут
Наш сервер 5 секунд ждет ответа о том, что вебхук обработан. Если вам этого времени может не хватать (много обработки, медленное соединение, высокая нагрузка), используйте механизм очередей — приняв вебхук, ставьте его обработку в очередь и отвечайте, что вебхук принят.
Вебхук
Вебхук — это способ оповещения клиента о произошедшем в системе событии с помощью пользовательских обратных вызовов по 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,запрашивайте данные и получайте настоящую нагрузку. Такой способ позволяет надежнее обрабатывать данные и не перегружать систему.