❮ Интеграции

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

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

Вебхук — это когда открытие исполняет не наш контроллер, а ваш сторонний сервис (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.