Вебхуки из правил

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

Перед началом

HAM Systems включает вебхуки для каждого аккаунта отдельно. Если приложение показывает Вебхуки не включены для вашей учётной записи, обратитесь в поддержку.
Вам нужен адрес https://, который принимает запросы POST из интернета.

Добавление вебхука в правило

Откройте Меню. В группе Инструменты нажмите Облачные правила.
Откройте правило или создайте новое правило. См. Создание правила.
В действиях нажмите Добавить действие.
Выберите в списке Webhook.
В поле URL введите адрес Вашей системы.
Если Вам также нужен вызов при сбросе правила, нажмите Добавить действие сброса и снова выберите Webhook.
Нажмите Сохранить.

Новое правило с условиями и действиями — Компьютер

Действие правила со значением Webhook и заполненным полем URL — Компьютер

Если адрес неправильный, приложение показывает Недействительный URL.

Запрос

Платформа отправляет POST с телом JSON (Content-Type: application/json):

{
  "event": "triggered",
  "rule": {
    "id": 4321,
    "name": "Fridge 1 temperature",
    "serialno": "e11:123",
    "this_data": [ { "...": "the rule conditions" } ]
  },
  "device_data": {
    "e11:123": {
      "R": { "T": 912, "GI": 1, "GIC": 0, "GI2": 1, "GI2C": 0 },
      "O": [],
      "S": { "...": "the device settings" }
    }
  },
  "messages": []
}

Поле	Содержимое
`event`	`triggered`, когда правило срабатывает. `resolved`, когда выполняется действие При сбросе.
`rule.id`, `rule.name`	Номер и название правила
`rule.serialno`	Устройство правила
`rule.this_data`	Условия правила
`device_data`	Текущее состояние каждого устройства правила, по серийному номеру. Тот же формат, что у обновлений WebSocket.
`messages`	Ошибки, например `Failed to get state of e11:123 for rule #4321`, когда состояние устройства недоступно

Значения в R необработанные. В примере T: 912 означает 9.12 °C. См. определения в REST API.

Платформа удаляет данные WiFi устройства (название сети, пароль и корпоративные данные) из device_data.

Защита вебхука

У запроса нет подписи (HMAC). Чтобы проверить, что запрос приходит от Вашего правила:

Создайте длинный случайный секрет, например командой openssl rand -hex 32.
Поместите секрет в строку запроса адреса: https://example.com/ham-hook?token=YOUR_SECRET.
В Вашей системе отклоняйте каждый запрос, у которого нет правильного token.

Правила и ограничения

Адрес должен начинаться с https://.
Платформа не вызывает локальные и частные адреса: localhost, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, 100.64.0.0/10, 0.0.0.0/8 и соответствующие адреса IPv6 (::1, fe80:, fc00::/7).
До 5 вызовов за 60 секунд для каждого действия webhook правила.
До 30 вызовов webhook за 60 секунд для каждого аккаунта.
Платформа пропускает вызовы сверх лимитов. Она не отправляет их позже.
Платформа не проверяет статус HTTP Вашего ответа и не отправляет запрос снова.
У действия может быть задержка (ПОСЛЕ). У правила всего до 12 действий.

Проверка

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

См. также

Чат с поддержкой