❮ Интеграции

Спецификация вебхука

Entrixy отправляет команду «Открыть» на ваш адрес и подписывает её. Здесь — формат запроса и проверка подписи, чтобы принять команду в своём сервисе, умном доме или на своей плате.

Вебхук — режим, в котором открытие исполняет не наш контроллер, а ваша собственная система: Home Assistant, реле в локальной сети, свой сервер. У объекта «Вебхук» два режима: приложение — HTTP-запрос по вашему адресу делает сам телефон, подставляя значения в шаблон URL; сервер — подписанный POST отправляет наш сервер, он и описан здесь. Готовые приёмники: curl, Flask, Home Assistant, Node.js.

Запрос

При открытии сервер Entrixy отправляет на ваш webhook_url POST с JSON-телом:

POST <ваш webhook_url>
Content-Type: application/json

{
  "action":    "open",
  "object_id": 42,
  "timestamp": 1750000000,
  "nonce":     "0011223344556677",
  "signature": "9d7b58066094fa88..."
}

Поле	Значение
`action`	`"open"` (для бистабильного также `"close"`)
`object_id`	id объекта в вашем аккаунте
`timestamp`	unix-время отправки (секунды)
`nonce`	16 hex-символов (8 случайных байт), одноразовый
`signature`	HMAC-SHA256, см. ниже

Поля timestamp, nonce и signature приходят, только если у объекта задан webhook_secret. Без секрета тело содержит одни {action, object_id}.

Подпись

Подписывается каноническая строка из четырёх полей через точку, а не само JSON-тело — так вам не придётся побайтно повторять нашу сериализацию:

base = "<timestamp>.<nonce>.<action>.<object_id>"
signature = HMAC-SHA256(webhook_secret, base)   // hex

webhook_secret вы задаёте при создании объекта «Веб-хук» в приложении. Гостям он не передаётся — сервер подписывает вашим секретом сам.

Как проверить (получатель)

Соберите ту же строку base = timestamp.nonce.action.object_id из принятых полей.
Посчитайте HMAC-SHA256(webhook_secret, base) и сверьте с signature через constant-time сравнение (hash_equals / hmac.compare_digest).
Анти-replay: отклоните, если |now − timestamp| > 300 секунд. По желанию — храните недавние nonce и отклоняйте повтор.
Подпись совпала, запрос свежий — выполняйте открытие.

Адрес вебхука обычно открыт без аутентификации, поэтому проверка подписи обязательна. Секрет берите не короче 16 символов, а лучше сгенерируйте: openssl rand -hex 32.

Тест-вектор

Прогоните свою проверку на этих значениях и сверьте подпись:

webhook_secret = webhook_secret_example_key
timestamp      = 1750000000
nonce          = 0011223344556677
action         = open
object_id      = 42

base       = 1750000000.0011223344556677.open.42
signature  = 9d7b58066094fa88acc0afa7aa805fc5f0d008d33cb11b8aa2366102da8e20f1
  = HMAC-SHA256(webhook_secret, base)

Ответ (опционально)

Ответьте 200 OK. Чтобы приложение показало результат, верните JSON {"level":"success","message":"..."} (level: success/warning/danger/info). Иначе просто 200.

Готовые приёмники

curl (тест-отправка + проверка), Flask и Node.js (скелеты сервисов), Home Assistant (webhook-автоматизация с HMAC). Реле без поддержки HMAC (Shelly, Tasmota) подключаются через прокси или Home Assistant.