Skip to main content

​
Webhooks

Webhooks são o caminho mais simples para um sistema externo disparar uma reação no Portal. Você cria uma automação com gatilho Webhook, o Portal te entrega um webhook_id, e seu sistema faz um POST quando algo acontecer.

​
Quando usar webhook?

  • Seu sistema (CRM, ERP, monitoramento, IFTTT, n8n, Zapier) precisa acionar dispositivos no Portal a partir de um evento dele.
  • Você não quer gerenciar token (o webhook_id já e o segredo).
  • A ação final e simples: ligar/desligar algo, mandar notificação, executar script.
Se você precisa de fluxo bidirecional (ler estado + agir), use PAT + chamada de serviço.

​
Configurando o webhook

1

Crie uma automação

No painel, va em Automações → Nova Automação.
2

Gatilho Webhook

Escolha Gatilho → Webhook. O Portal gera um webhook_id (uma string aleatoria longa).
3

Defina as ações

Adicione as ações que devem rodar quando o webhook for chamado.
4

Copie a URL

A URL final e:
https://portal.unicontrol.me/v1/automations/webhook/{webhook_id}

​
Chamando o webhook

curl -X POST https://portal.unicontrol.me/v1/automations/webhook/abc123xyz \
  -H "Content-Type: application/json" \
  -d '{
    "evento": "porta_aberta",
    "local": "garagem",
    "timestamp": "2026-05-28T14:00:00-03:00"
  }'
Webhooks não exigem header Authorization. O próprio webhook_id na URL e o segredo.
A resposta padrão e 200 OK com corpo vazio. Erros possíveis: 404 (webhook não existe ou foi revogado).

​
Usando o payload nas ações

O body JSON enviado fica disponível nas ações da automação via templates. Exemplos:
TemplateResultado
{{ trigger.json.evento }}porta_aberta
{{ trigger.json.local }}garagem
Você pode usar isso, por exemplo, para enviar uma notificação dinâmica: 
Acao: Notificacao
Mensagem: "Porta aberta em {{ trigger.json.local }}"

​
Boas práticas

  • Rotacione webhooks comprometidos: se desconfiar de vazamento, exclua a automação e recrie com novo webhook_id.
  • Valide o payload: a automação pode começar com uma condição verificando campos esperados.
  • Não exponha em frontend público: o webhook_id na mao errada permite acionar ações na sua casa. Use webhook apenas em sistemas controlados (backend-to-backend, n8n self-hosted, etc.).
  • Idempotencia: se o seu sistema externo pode retry, deixe a automação tolerante a chamadas duplicadas (ex: não adicione duas vezes o mesmo item).

​
Webhooks no caminho contrario (Portal → seu sistema)

Para o Portal enviar dados pro seu sistema quando algo acontece, use uma automação com:
  • Gatilho: o evento que quer monitorar (mudança de estado, horário, etc.)
  • Ação: Chamar URL (HTTP request) apontando pro seu endpoint
Acao: Chamar URL
Metodo: POST
URL: https://meu-servico.exemplo.com/portal-hook
Body: { "entity_id": "{{ trigger.entity_id }}", "state": "{{ trigger.to_state.state }}" }
Adicione header Authorization na própria configuração da ação se seu endpoint exige autenticação.