Webhooks das regras

Uma regra pode chamar um URL quando é acionada. Assim, o seu próprio sistema sabe de um evento de imediato, por exemplo uma temperatura alta ou a desligação de um dispositivo.

Antes de começar

A HAM Systems ativa os webhooks por conta. Se a aplicação mostra Os webhooks não estão ativados na sua conta, contacte o apoio.
Precisa de um endereço https:// que aceita pedidos POST da internet.

Adicionar um webhook a uma regra

Abra o Menu. No grupo Ferramentas, toque em Regras na nuvem.
Abra uma regra ou crie uma regra nova. Consulte criar uma regra.
Nas ações, toque em Adicionar ação.
Na lista, selecione Webhook.
No campo URL, escreva o endereço do seu sistema.
Se quer também uma chamada quando a regra repõe, toque em Adicionar ação de reposição e selecione Webhook outra vez.
Toque em Guardar.

Uma regra nova com condições e ações — Computador

Uma ação de regra definida como Webhook, com o campo URL preenchido — Computador

Se o endereço não está correto, a aplicação mostra O URL não é válido.

O pedido

A plataforma envia um POST com um corpo 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": []
}

Campo	Conteúdo
`event`	`triggered` quando a regra é acionada. `resolved` quando uma ação Ao repor é executada.
`rule.id`, `rule.name`	O número e o nome da regra
`rule.serialno`	O dispositivo da regra
`rule.this_data`	As condições da regra
`device_data`	O estado atual de cada dispositivo da regra, com o número de série como chave. O mesmo formato das atualizações do WebSocket.
`messages`	Erros, por exemplo `Failed to get state of e11:123 for rule #4321` quando o estado de um dispositivo não está disponível

Os valores em R são em bruto. No exemplo, T: 912 significa 9.12 °C. Veja as definições na API REST.

A plataforma remove de device_data os dados do WiFi do dispositivo (nome da rede, palavra-passe e dados empresariais).

Proteger o webhook

O pedido não tem assinatura (HMAC). Para verificar que o pedido vem da sua regra:

Crie um segredo longo e aleatório, por exemplo com openssl rand -hex 32.
Coloque o segredo na query string do endereço: https://example.com/ham-hook?token=YOUR_SECRET.
No seu sistema, rejeite cada pedido que não tem o token correto.

Regras e limites

O endereço tem de começar com https://.
A plataforma não chama endereços locais e privados: 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 e os endereços IPv6 relacionados (::1, fe80:, fc00::/7).
Até 5 chamadas por 60 segundos para cada ação de webhook de uma regra.
Até 30 chamadas de webhook por 60 segundos para cada conta.
A plataforma ignora as chamadas acima dos limites. Não as envia mais tarde.
A plataforma não verifica o estado HTTP da sua resposta e não envia o pedido outra vez.
Uma ação pode ter um atraso (APÓS). Uma regra tem até 12 ações no total.

Teste

Para um primeiro teste, utilize um serviço público que mostra os pedidos que recebe. Crie uma regra com uma condição fácil e veja o corpo do pedido.

Consulte também

Chat com o suporte