Subscription to facilitate delivery of lite account webhooks что это
Webhooks для платежей
Webhooks для платежей (ранее «Обновления в режиме реального времени») — это очень важный метод, который позволяет быть в курсе изменений в заказах, сделанных с помощью Платежей Facebook в вашем приложении.
Общие сведения
Webhooks — это система на основе подписей между Facebook и вашим сервером. С ее помощью подписчики вашего приложения смогут получать обновления от Facebook через заданный эндпойнт HTTPS. В случае изменений в заказе, сделанном через приложение, мы отправим на этот эндпойнт запрос POST HTTPS, чтобы уведомить ваш сервер об обновлении.
Обычно обновления отправляются на сервер разработчика в 3 случаях:
Подписка на Webhooks
Чтобы подписаться на Webhooks для платежей, сначала создайте общедоступный URL эндпойнта, на который будут приходить GET HTTPS для подтверждения подписки и POST для запросов на изменение данных. Ниже описана структура обоих видов запросов. Далее настройте подписки на объект payment своего приложения. Это можно сделать 2 способами:
В обоих случаях эндпойнт будет получать одни и те же данные одним и тем же способом. Подробнее о том, что будет получать ваш сервер, см. в разделе Ваш сервер обратного вызова.
Подписка через Панель приложений
На этой странице будет отображен статус подписки вашего приложения вне зависимости от того, была ли подписка оформлена через панель или через API. Здесь можно изменить URL обратного вызова подписки и протестировать его.
В поле «Обратный вызов» укажите действительный общедоступный эндпойнт сервера. С помощью этого адреса мы будем подтверждать подписку и отправлять обновления. Этот адрес должен отвечать согласно инструкциям в разделе Ваш сервер обратного вызова
Затем нужно предоставить «Маркер подтверждения». Этот маркер будет отправлен на этапе регистрации для подтверждения, что подписка оформлена из безопасного источника. Маркер не будет отправляться со стандартными обновлениями Webhook.
Тестирование настроек
После того как вы введете параметры подписки, не забудьте нажать кнопку «Сохранить изменения» внизу страницы. Если вам понадобится редактировать подписку, просто измените содержимое полей, повторите тестирование и снова сохраните форму.
Подписка через API Graph
Настроить и указать подписки можно программными средствами — через API Graph. Для этого вам понадобится access token приложения, который можно узнать в инструменте маркера доступа или с помощью эндпойнта /oauth API Graph.
API Subscription доступен на эндпойнте https://graph.facebook.com/[APP_ID]/subscriptions
С его помощью можно выполнить 3 задачи:
Добавление и изменение подписок
Чтобы настроить подписку, отправьте POST со следующими параметрами. Обратите внимание, что эти параметры соответствуют полям в описанной выше форме:
Когда мы получаем этот запрос, как и в случае с конфигурацией формы выше, мы выполним GET к вашему обратному вызову, чтобы проверить, что он действует и готов получать обновления. В частности, ваш эндпойнт должен возвращать hub.challenge на Facebook.
Обратите внимание, что поскольку для каждого типа объекта у приложения может быть только одна подписка, если для этого типа объекта подписка уже есть, новые опубликованные данные заменят существующие.
Указание подписок
Если отправить GET HTTPS к API Subscription, будет возвращен файл в формате JSON со списком ваших подписок. Например:
С помощью Graph Explorer вы можете поэкспериментировать с этим API, но при этом не забывайте использовать маркер доступа своего приложения.
Ваш сервер обратного вызова
Ваш сервер обратного вызова должен обрабатывать 2 типа запросов. Убедитесь, что он размещен по общедоступному URL, чтобы мы могли выполнять эти запросы.
Подтверждение подписки
Сначала серверы Facebook выполнят один GET HTTPS к вашему URL обратного вызова, когда вы попытаетесь добавить или изменить подписку. К URL обратного вызова добавляется строка запроса со следующими параметрами:
В этом параметре передается строка « subscribe »
Получение уведомлений об обновлениях
После оформления подписки мы будем отправлять POST HTTPS на эндпойнт вашего сервера при каждом изменении (в выбранных полях или связях). В ответ на этот запрос вам необходимо будет отправлять 200 HTTP.
Примечание. Любой ответ HTTP кроме 200 считается ошибкой. При получении неподходящих ответов мы будем повторно отправлять обновление Webhooks. В случае неправильных ответов вы можете получить одно и то же обновление несколько раз.
Примечание для разработчиков PHP. Чтобы получить закодированные данные в PHP, выполните следующий код:
Вот пример обратного вызова для подписки объекта payments :
Примечание. Хотя Webhooks для остальных типов объектов можно объединять в пакеты, обновления о платежах нельзя объединять.
Вы будете получать обновление каждый раз, когда пользователь или разработчик будут менять какую-либо транзакцию.
В случае сбоя отправки обновления на сервер мы практически сразу повторим попытку. Затем, в течение следующих 24 часов, мы будем повторять отправку снова и снова, постепенно увеличивая промежутки времени между попытками.
Отклик на обновление
В разделах ниже перечислены все вероятные изменения статуса, после которых отправляется обновление. Их можно разделить на две группы:
Действия
Вот пример отклика от API Graph на объект платежа со связанными действиями:
Поскольку при регистрации на Webhooks вы подписались на поле «actions», мы будем отправлять обновления при следующих изменениях в массиве:
Списание
Возврат средств
Возврат платежа, отмена возврата платежа и отклонение
Как и в случае с возвратом средств, вы будете получать уведомления о возврате платежа, отмене возврата платежа и отклонении. Объект возврата платежа, отмены возврата платежа или отклонения будет добавлен в массив «actions» возвращенных данных API Graph о платеже.
Споры
Ниже представлен пример отклика от API Graph на оспоренную транзакцию:
Подробнее о том, как отвечать на споры и возвращать средства, читайте в разделе Руководство по платежам: разрешение споров и возврат средств.
Webhook Subscription
The methods are used to manage the subscription of webhooks to be sent to the client’s URL.
Since the CDEK test account is common for all clients, only production CDEK URL should be used for testing the webhooks.
Specify your test URL to which the webhooks are to be sent, in your request for subscription. After completion of the testing, change it to your production URL.
1.Adding the Subscription
The method is used to add the webhook subscription.
At present, you can subscribe for order status events and print forms readiness.
Request for Adding the Subscription
In order to use this process, a POST request should be sent to URL: https://api.cdek.ru/v2/webhooks.
The request body should be sent in the JSON format (Content-Type: application/json).
The following fields are supported:
Field name
Description
Field type
Mandatory (yes/no)
URL to which the client wants to receive webhooks
1 If the client already has a subscription with the specified type, the previous url will be changed to a new one.
Response to the Request for Adding the Subscription
The response body is returned in the JSON format:
Field name
Description
Field type
Mandatory (yes/no)
May take on values: CREATE, UPDATE, DELETE, AUTH, GET
Current status of the request
May take on values:
2. Details of Subscription
The method is used to get details of client’s webhook subscription(-s).
Request for Details of Subscription
In order to use this process, a GET request should be sent to URL:
details of all current subscriptions: https://api.cdek.ru/v2/webhooks
Response to the Request for Details of Subscription
The response body is returned in the JSON format:
Field name
Description
Field type
Mandatory (yes/no)
URL to which webhooks are sent for the client
May take on values: CREATE, UPDATE, DELETE, AUTH, GET
Current status of the request
May take on values:
3. Deleting the Subscription
The method is used to delete the webhook subscription.
Request for Deleting the Subscription
In order to use this process, a DELETE request should be sent to URL:
Response to the Request for Deleting the Subscription
The response body is returned in the JSON format:
Field name
Description
Field type
Mandatory (yes/no)
Identifier of the deleted subscription
May take on values: CREATE, UPDATE, DELETE, AUTH, GET
Current status of the request
May take on values:
The methods are used to manage the subscription of webhooks to be sent to the client’s URL.
Since the CDEK test account is common for all clients, only production CDEK URL should be used for testing the webhooks.
Specify your test URL to which the webhooks are to be sent, in your request for subscription. After completion of the testing, change it to your production URL.
1.Adding the Subscription
The method is used to add the webhook subscription.
At present, you can subscribe for order status events and print forms readiness.
Request for Adding the Subscription
In order to use this process, a POST request should be sent to URL: https://api.cdek.ru/v2/webhooks.
The request body should be sent in the JSON format (Content-Type: application/json).
The following fields are supported:
Field name
Description
Field type
Mandatory (yes/no)
URL to which the client wants to receive webhooks
1 If the client already has a subscription with the specified type, the previous url will be changed to a new one.
Response to the Request for Adding the Subscription
The response body is returned in the JSON format:
Field name
Description
Field type
Mandatory (yes/no)
May take on values: CREATE, UPDATE, DELETE, AUTH, GET
Current status of the request
May take on values:
2. Details of Subscription
The method is used to get details of client’s webhook subscription(-s).
Request for Details of Subscription
In order to use this process, a GET request should be sent to URL:
details of all current subscriptions: https://api.cdek.ru/v2/webhooks
Response to the Request for Details of Subscription
The response body is returned in the JSON format:
Реализация вебхуков на примере взаимодействия сторонних сервисов с онлайн-кассами
Я попросил нашу команду маркетинга нарисовать иллюстрацию и долго объяснял, что такое вебхуки
Не так давно передо мной встала задача реализовать работу вебхуков в Личном кабинете владельца кассы компании Дримкас. Как оказалось, в сети практически нет описания и туториалов, как это сделать. Я расскажу, как мы это реализовали без тяжелых кронов по БД.
Статья будет полезна для 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 факта
Система уведомлений о событиях (Webhooks)
Webhook — механизм оповещения пользователей системы о событиях. События, о которых может уведомлять Webhook:
Webhook используют для отслеживания изменения статусов писем в реальном времени.
Модель, используемая в Webhook, работает следующим образом: при возникновении события установленный ранее обработчик отправляет JSON на URL, который был указан для этого Webhook. Используются стандартные порты: 80 порт для HTTP и 443 порт для HTTPS. Для установки Webhook на URL с указанным портом можно передавать URL в виде: http://11.111.111.11:80
Если URL, на который отправляется Webhook, недоступен (отвечает не HTTP 200 OK, таймаут — 3 секунды), попытки отправки Webhook на этот URL до получения ожидаемого 200 ОК будут продолжаться в течение 24 часов с интервалом в 10 минут с дополнительным параметром retry_count, значение которого будет увеличиваться на 1 с каждой повторной отправкой Webhook.
Если в течение 24 часов вебхук не удалось доставить, попытки отправки прекращаются, а статус вебхука меняется на stopped. На почту аккаунта отправляется уведомление об остановке вебхука с указанием последнего ответа. Чтобы активировать остановленный вебхук, исправьте ошибку, затем включите вебхук с помощью API метода setHook с параметром status=»active» или смените статус в личном кабинете.
Установить обработчик
setHook — установить/заменить обработчик оповещений о событиях определенного типа.
| Синтаксис и URL для вызова метода |
| setHook (hook_url, events, [event_format, max_parallel, single_event, status ]) |
| https://api.unisender.com/ru/api/setHook?api_key=KEY&hook_url=URL&event_format=FORMAT&events[]=EVENT&max_parallel=NUM &single_event=1&status=active |
| Аргументы | |||||||||||||||||
| api_key* | ключ доступа к API | ||||||||||||||||
| hook_url * | на какой URL отправлять запрос при возникновении события. Фактически является идентификатором обработчика. При повторном вызове setHook с таким же hook_url данные обработчика будет заменены. | ||||||||||||||||
| event_format | формат, в котором передаются данные о событии, обязательный параметр с тремя вариантами значений:
| ||||||||||||||||
| max_parallel | необязательное указание максимального количество параллельных вызовов к этому обработчику. По умолчанию равно 10. | ||||||||||||||||
| single_event | Принимает значения 1 и 0. По умолчанию: 0 1 — оповещение Webhook не содержит массивов, за одно оповещение информация будет возвращаться только по одному событию; | ||||||||||||||||
| status | Статус обработчика. Допустимые значения: active — обработчик активен; disabled — обработчик отключён. | ||||||||||||||||
Пример вызова
Список обработчиков
listHooks — получить список всех обработчиков.
| Синтаксис и URL для вызова метода |
| listHooks () |
| https://api.unisender.com/ru/api/listHooks?api_key=KEY |
| Аргументы | |
| api_key * | ключ доступа к API |
| Возвращаемое значение |
Удалить обработчик
removeHook — удалить обработчик оповещений.
| Синтаксис и URL для вызова метода |
| removeHook (hook_url) |
| https://api.unisender.com/ru/api/removeHook?api_key=KEY&hook_url=URL |
| Аргументы | |
| api_key * | ключ доступа к API |
| hook_url* | URL-идентификатор удаляемого обработчика |
Формат оповещений (JSON)
Пример возвращаемого оповещения
Описание параметров оповещения (для single_event = 0)
Данные оповещения — JSON-объект со следующими полями:
Для генерации auth нужно сформировать полностью тело оповещения в JSON, вместо значения auth подставить значение api_key пользователя и вычислить md5 от тела. Затем заменить в сообщении api_key на получившийся md5, записанный в шестнадцатеричном виде в lowercase.
Для проверки auth надо заменить его значение на api_key, также вычислить md5 от тела оповещения и сверить его со значением auth, полученном в изначальном теле оповещения.
Управление вебхуками в личном кабинете
В личном кабинете кликните на ваш email в правом верхнем углу и выберите «Настройки».
На панели слева перейдите в раздел «Webhook».
Если нужно выключить активный вебхук, кликните на active.
Чтобы активировать выключенный вебхук, кликните на disabled.
Если вебхук остановлен из-за ошибок, для активации нажмите на stopped.
Если при отправке вебхуков на ваш URL возникали ошибки, кликните на пункт «История ошибок», чтобы их посмотреть.