Вебхуки

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

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

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

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

{
 "events":
  [
   {"meta":
     {
       "type":"product",
       "href":"https://online.moysklad.ru/api/remap/1.1/entity/product/c1557cfb-c2cc-11e6-7a31-d0fd000f0b00"
     },
    "action":"DELETE"
   }
  ]
}

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

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

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

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

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

  • создание заказов покупателей и изменение их статусов
  • изменение цены товара
  • обновление номера телефона контрагента

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

Вебхуки в JSON API

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

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

  • CREATE,
  • UPDATE,
  • DELETE.

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

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

curl -X POST \
  https://online.moysklad.ru/api/remap/1.1/entity/webhook \
  -H 'Authorization: Basic token==' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "http://www.example.com",
  "action": "CREATE",
  "entityType": "service"
}'

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

{
    "meta": {
        "href": "https://online.moysklad.ru/api/remap/1.1/entity/webhook/a5b3cd1f-caee-11e8-9ff4-34e80022dcb3",
        "metadataHref": "https://online.moysklad.ru/api/remap/1.1/entity/webhook/metadata",
        "type": "webhook",
        "mediaType": "application/json"
    },
    "id": "a5b3cd1f-caee-11e8-9ff4-34e80022dcb3",
    "accountId": "45eb22e0-0e7b-11e2-1c31-3c4a92f3a0a7",
    "entityType": "service",
    "url": "http://www.example.com",
    "method": "POST",
    "enabled": true,
    "action": "CREATE"
}

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

curl -X GET \
  https://online.moysklad.ru/api/remap/1.1/entity/webhook/a5b3cd1f-caee-11e8-9ff4-34e80022dcb3 \
  -H 'Authorization: Basic token==' \
  -H 'Content-Type: application/json' \

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

curl -X PUT \
  https://online.moysklad.ru/api/remap/1.1/entity/webhook/a5b3cd1f-caee-11e8-9ff4-34e80022dcb3 \
  -H 'Authorization: Basic token==' \
  -H 'Content-Type: application/json' \
  -d '{
  "action": "UPDATE"
}'

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

curl -X PUT \
  https://online.moysklad.ru/api/remap/1.1/entity/webhook/a5b3cd1f-caee-11e8-9ff4-34e80022dcb3 \
  -H 'Authorization: Basic token==' \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": false
}'

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

curl -X DELETE \
  https://online.moysklad.ru/api/remap/1.1/entity/webhook/a5b3cd1f-caee-11e8-9ff4-34e80022dcb3 \
  -H 'Authorization: Basic token==' \
  -H 'Content-Type: application/json' \

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

curl -X GET \
  https://online.moysklad.ru/api/remap/1.1/entity/webhook \
  -H 'Authorization: Basic token==' \
  -H 'Content-Type: application/json' \

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

{
   "context":{
      "employee":{
         "meta":{
            "href":"https://online.moysklad.ru/api/remap/1.1/context/employee",
            "metadataHref":"https://online.moysklad.ru/api/remap/1.1/entity/employee/metadata",
            "type":"employee",
            "mediaType":"application/json"
         }
      }
   },
   "meta":{
      "href":"https://online.moysklad.ru/api/remap/1.1/entity/webhook",
      "type":"webhook",
      "mediaType":"application/json",
      "size":1,
      "limit":25,
      "offset":0
   },
   "rows":[
      {
         "meta":{
            "href":"https://online.moysklad.ru/api/remap/1.1/entity/webhook/a5b3cd1f-caee-11e8-9ff4-34e80022dcb3",
            "metadataHref":"https://online.moysklad.ru/api/remap/1.1/entity/webhook/metadata",
            "type":"webhook",
            "mediaType":"application/json"
         },
         "id":"a5b3cd1f-caee-11e8-9ff4-34e80022dcb3",
         "accountId":"45eb22e0-0e7b-11e2-1c31-3c4a92f3a0a7",
         "entityType":"service",
         "url":"http://www.example.com",
         "method":"POST",
         "enabled":true,
         "action":"CREATE"
      }
   ]
}

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

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

  • вебхуки доступны только на платном тарифе
  • работа с вебхуками доступна только администратору аккаунта
  • работа с вебхуками возможна только через JSON API

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

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

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

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

Для проверки работоспособности вебхука удобен сервис https://webhook.site/ . Он создает уникальный тестовый url, который необходимо указать в вебхуке, и интерактивно показывает входящие запросы, т.е. уведомления вебхуков.

  1. Переходим на сайт useful image
  2. Получаем уникальный url. Необходимо скопировать его, чтобы использовать при создании вебхука. useful image
  3. Создаем вебхук, в примере ниже вебхук на создание услуги 
    curl -X POST \
  https://online.moysklad.ru/api/remap/1.1/entity/webhook \
  -H 'Authorization: Basic token==' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://webhook.site/c314f269-d524-4b1a-bf9e-5c59060b220c",
  "action": "CREATE",
  "entityType": "service"
}'
  4. Создаем услугу в МоемСкладе, в примере ниже создание услуги через JSON API 
    curl -X POST \
  https://online.moysklad.ru/api/remap/1.1/entity/service \
  -H 'Authorization: Basic token==' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Заточка коньков"
}'
  5. На наш уникальный адрес пришло уведомление! useful image
Tags: getting_started api webhook