Automações
Gatilho por Webhook
HTTP/1.1 e HTTP/2 fornecem a base de transporte usada por webhooks, mas não definem a lógica da automação. Um gatilho por webhook expõe uma URL que, ao receber requisição válida, inicia um fluxo e pode disponibilizar payload, cabeçalhos e parâmetros. É uma integração de baixo custo para serviços que não mantêm conexão contínua, porém exige endpoint acessível, autenticação, TLS, validação e proteção contra repetição; publicar uma URL secreta sem controles não é suficiente.
⚙ Definição Técnica
Gatilho por webhook é um ponto de entrada orientado a eventos no qual o motor de automação associa uma rota HTTP a uma regra e inicia a execução quando recebe uma requisição que satisfaz método, autenticação e validação configurados. A requisição pode transportar dados em JSON, formulário, query string, cabeçalhos ou corpo binário, e esses dados podem ser expostos como variáveis do gatilho. A implantação requer um caminho de rede entre o emissor e o endpoint, preferencialmente HTTPS com autenticação e verificação de integridade, além de política para duplicidade, timeout, resposta e limitação de taxa.
Tipos comuns de gatilhos
Webhook interno na rede local
O endpoint fica acessível apenas na LAN, VLAN autorizada ou rede privada. Um NVR, servidor, ESPHome, Node-RED ou sistema de alarme envia HTTP para o controlador quando ocorre um evento. A arquitetura reduz exposição à internet e pode manter baixa latência mesmo sem conexão externa. O requisito é roteamento e política de firewall entre as redes. Se IoT está isolada, permita apenas origem, destino, porta e método necessários. DNS local e certificados internos podem ser usados. A limitação é que serviços em nuvem não alcançam o endpoint sem túnel, proxy ou relay. Para alta confiabilidade, endereços, nomes e certificados precisam sobreviver a reinícios e mudanças de DHCP.
Webhook público protegido por HTTPS
O controlador publica uma URL por proxy reverso, gateway de API, túnel ou serviço de relay para receber eventos externos. TLS protege o tráfego, mas não autentica automaticamente o emissor. O endpoint deve exigir segredo em cabeçalho, assinatura HMAC, mTLS, token de curta duração ou mecanismo do provedor. URL difícil de adivinhar é camada adicional, não controle único. Firewall, WAF e rate limiting reduzem abuso. Logs precisam evitar registrar segredos. O certificado deve renovar automaticamente. A exposição amplia interoperabilidade com GitHub, serviços de pagamento, plataformas de monitoramento e nuvens de dispositivos, mas também aumenta superfície de ataque e dependência de DNS e internet.
Webhook com payload JSON estruturado
A requisição usa Content-Type application/json e envia campos como event_type, device_id, timestamp e data. O gatilho valida schema, tipos, campos obrigatórios e tamanho antes de executar. A automação pode escolher caminhos conforme event_type e usar dados. O payload não deve ser confiado apenas porque veio de endpoint conhecido. Valores precisam de limites, unidades e allowlist. Um campo brightness de 500 não deve ser encaminhado diretamente a uma lâmpada que aceita 0–100. Strings usadas em templates precisam de escape. JSON Schema ou validação equivalente reduz. Versão do contrato deve ser incluída para evoluir sem quebrar fluxos.
Webhook assinado pelo emissor
O provedor calcula HMAC ou assinatura sobre o corpo e inclui timestamp e identificador em cabeçalhos. O receptor reconstrói a mensagem canônica e compara a assinatura em tempo constante. O timestamp limita replay, e o identificador permite deduplicação. Cada provedor define algoritmo e formato. GitHub, Stripe e outras plataformas usam padrões próprios de assinatura. A implementação precisa validar o corpo bruto antes de parsear quando a assinatura cobre bytes exatos. Modificar espaços ou reserializar JSON altera o hash. Segredos devem ficar em cofre e ser rotacionados. Durante rotação, duas chaves podem ser aceitas por janela controlada.
Webhook com resposta síncrona
Além de iniciar a automação, o endpoint retorna status e conteúdo ao chamador. Respostas 2xx indicam aceitação ou conclusão conforme contrato; 4xx representam erro do cliente; 5xx, falha temporária do servidor. Se a automação demora, é melhor responder 202 Accepted e processar em segundo plano, porque provedores aplicam timeout de 3–30 s. Esperar ações físicas pode causar retentativa e duplicidade. A resposta pode incluir event_id e URL de consulta. O motor precisa definir se a execução é síncrona ou enfileirada. Nunca retorne dados sensíveis desnecessários.
Considerações de Implementação
Retentativas podem executar a mesma ação mais de uma vez
Emissores repetem webhooks quando não recebem resposta ou obtêm 5xx. A primeira requisição pode ter sido processada e a resposta perdida. Destravar uma porta, cobrar, criar registro ou alternar um estado duas vezes pode produzir consequência. O payload deve trazer identificador único, ou o receptor deve derivar chave idempotente. A automação registra IDs processados por período e devolve sucesso para duplicatas sem repetir efeito. Operações devem preferir estado desejado, como set light on, em vez de toggle. Toggle não é idempotente: duas entregas anulam o resultado.
Endpoint exposto exige autenticação e validação em camadas
Uma URL secreta pode aparecer em logs, histórico do navegador, repositório, analytics ou mensagem. Use HTTPS e método autenticado. Valide assinatura, timestamp, origem quando possível, content type, tamanho, schema e valores. Rate limiting impede abuso. A conta que executa a automação deve ter menor privilégio. Um webhook de notificação não precisa permissão para abrir fechaduras. Separe endpoints por função e risco. Respostas não devem revelar configuração. Logs devem registrar event_id e resultado sem armazenar tokens ou payloads pessoais além do necessário.
Timeout e fila precisam ser definidos pelo contrato
Provedores esperam resposta em janela curta e podem retentar. A automação física pode depender de hub, rádio e dispositivo e levar segundos. O endpoint deve validar, persistir o evento e responder rapidamente. O processamento segue em fila. Em caso de indisponibilidade, a fila pode reter e aplicar backoff. Há limite de idade: um evento “movimento detectado” entregue 30 min depois talvez não deva acender luz. Cada tipo precisa de TTL. Eventos de auditoria podem ser processados tarde. O sistema deve diferenciar. Métricas de atraso e dead-letter ajudam.
Observabilidade deve correlacionar requisição e execução
Cada webhook precisa de request_id ou event_id propagado para o trace da automação. Registre hora de recebimento, origem autenticada, versão, validação, status, duração e resultado. Não registre segredos. Quando o emissor relata sucesso e a ação não ocorreu, a correlação mostra se falhou no endpoint, condição, fila ou dispositivo. Dashboards podem acompanhar taxa 2xx, 4xx, 5xx, duplicatas e latência. Alertas devem considerar volume normal. Um pico pode ser ataque ou loop de integração.