❮ Integrações

Especificação do webhook

O Entrixy envia um comando Abrir para o seu endereço e assina-o. Aqui está o formato do pedido e como verificar a assinatura, para poder aceitar o comando no seu próprio serviço, casa inteligente ou placa.

O webhook é o modo em que a abertura não é feita pelo nosso controlador, mas pelo seu próprio sistema: Home Assistant, um relé na rede local, o seu próprio servidor. Um objeto Webhook tem dois modos: aplicação — o próprio telemóvel faz o pedido HTTP ao seu endereço, preenchendo os valores no modelo do URL; servidor — o nosso servidor envia um POST assinado, que é o que esta página descreve. Recetores já prontos: curl, Flask, Home Assistant, Node.js.

O pedido

Ao abrir, o servidor Entrixy envia um POST para o seu webhook_url com um corpo JSON:

POST <your webhook_url>
Content-Type: application/json

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

Campo	Valor
`action`	`"open"` (para objetos biestáveis também `"close"`)
`object_id`	o id do objeto na sua conta
`timestamp`	hora unix de envio, em segundos
`nonce`	16 carateres hex (8 bytes aleatórios), de uso único
`signature`	HMAC-SHA256, ver abaixo

Os campos timestamp, nonce e signature só chegam se o objeto tiver um webhook_secret. Sem segredo, o corpo leva apenas {action, object_id}.

A assinatura

O que se assina é uma cadeia canónica de quatro campos separados por pontos, e não o corpo JSON em si, por isso não tem de reproduzir a nossa serialização byte a byte:

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

webhook_secret define-se ao criar o objeto Webhook na aplicação. Os convidados nunca o recebem — o servidor assina ele próprio com o seu segredo.

Como verificá-la (do seu lado)

Construa a mesma cadeia base = timestamp.nonce.action.object_id a partir dos campos recebidos.
Calcule HMAC-SHA256(webhook_secret, base) e compare-o com signature com uma comparação de tempo constante (hash_equals / hmac.compare_digest).
Antirrepetição: rejeite o pedido se |now − timestamp| > 300 segundos. Opcionalmente, guarde os últimos nonce valores e rejeite repetições.
Se a assinatura bate certo e o pedido é recente, execute a abertura.

Um endereço de webhook costuma estar aberto sem autenticação, por isso verificar a assinatura é obrigatório. Use um segredo com pelo menos 16 carateres, ou melhor ainda, gere um: openssl rand -hex 32.

Vetor de teste

Passe a sua verificação por estes valores e confira a assinatura:

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)

A resposta (opcional)

Responda com 200 OK. Para que a aplicação mostre um resultado, devolva o JSON {"level":"success","message":"..."} (level: success/warning/danger/info). Caso contrário, basta 200.

Recetores já prontos

curl (envio de teste e verificação), Flask e Node.js (esqueletos de serviço), Home Assistant (uma automação de webhook com HMAC). Os relés sem suporte a HMAC (Shelly, Tasmota) ligam-se através de um proxy ou o Home Assistant.