Webhooks

Os webhooks conectam o dAio aos seus próprios sistemas. Em vez de consultar a plataforma continuamente, deixa que o dAio o avise: assim que ocorre um evento — um alerta meteorológico acionado, um risco elevado detetado — o dAio envia em tempo real um pedido HTTP assinado para o endpoint da sua escolha. Automatiza assim os seus fluxos de trabalho: abertura de tickets, notificações internas, atualização de um painel de negócio ou acionamento de um plano de ação no terreno.

É a ponte entre os alertas do dAio e o seu sistema de informação.

Dica : comece com um único webhook subscrito a um só tipo de evento, valide a cadeia de ponta a ponta e depois alargue. Evitará inundar os seus sistemas com notificações antes de ter fiabilizado o processamento.

Configurar um webhook

1. Aceda a Definições > Webhooks.
2. Clique em Novo webhook.
3. Indique o URL de destino: o endpoint HTTPS do seu servidor (ex. https://votre-serveur.com/webhook).
4. Selecione os eventos a escutar clicando nas etiquetas correspondentes.
5. Confirme com Criar.

Na criação é gerado automaticamente um segredo. Serve para assinar cada pedido com HMAC-SHA256 (ver mais abaixo): guarde-o do lado do servidor, pois permite-lhe verificar que cada chamada provém efetivamente do dAio.

Atenção : o URL deve ser HTTPS e acessível publicamente. Um endpoint em HTTP simples ou atrás de uma firewall fechada não poderá receber as entregas.

Eventos disponíveis

Evento	Descrição
weather.alert	Foi acionado um alerta meteorológico num site
weather.threshold	Foi ultrapassado um limiar meteorológico personalizado
air_quality.alert	Foi emitido um alerta de qualidade do ar
pollen.alert	Foi emitido um alerta de pólen
marine.alert	Foi emitido um alerta de condições marítimas
frost.alert	Foi acionado um alerta de geada
storm.alert	Foi acionado um alerta de trovoada / tempestade
business.risk_high	Foi detetado um nível de risco elevado para a sua atividade

Dica : subscreva cada webhook apenas aos eventos realmente utilizados pelo sistema destinatário. Um endpoint «tickets» não precisa de receber os mesmos eventos que um endpoint «painel».

Formato do payload

Cada entrega é um pedido POST cujo corpo é um objeto JSON. A estrutura geral é a seguinte:

{
  "event": "weather.alert",
  "timestamp": "2026-06-30T08:15:00Z",
  "data": {
    "site_id": 42,
    "site_name": "Entrepôt Nord",
    "severity": "high",
    "message": "Vent fort attendu (rafales > 80 km/h)"
  }
}

O campo event identifica o tipo de evento, timestamp indica a data de emissão (UTC, formato ISO 8601) e data contém os detalhes próprios do evento.

Autenticação HMAC-SHA256

Cada pedido é assinado com o seu segredo através de HMAC-SHA256. A assinatura é transmitida no cabeçalho X-Daio-Signature, no formato sha256=<signature>.

Verifique sistematicamente esta assinatura antes de processar um pedido: é o que garante que a chamada provém do dAio e que o payload não foi alterado.

Verificação do lado do servidor (Python):

import hmac, hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Atenção : calcule a assinatura sobre o corpo bruto do pedido (os bytes recebidos), antes de qualquer desserialização JSON. A mínima reformatação altera o hash e faz a verificação falhar.

Testar e depurar

• Clique no ícone Testar (▶) ao lado de um webhook para enviar um evento fictício ao seu endpoint.
• Uma resposta HTTP 2xx confirma que o seu servidor recebeu e aceitou o pedido.
• Expanda o webhook para consultar as suas últimas entregas: código HTTP, tipo de evento e data/hora.
• Um ponto colorido indica o estado do webhook: verde = ativo, vermelho = desativado após falhas repetidas.

Histórico de entregas

Cada envio é registado. Expanda um webhook para ver, em cada tentativa:

• O código HTTP de resposta (verde se < 300, vermelho caso contrário)
• O tipo de evento entregue
• A data e a hora da tentativa

Surge um contador de falhas no webhook quando algumas entregas falharam.

Tentativas e fiabilidade

O dAio tenta novamente a entrega automaticamente em caso de falha, com intervalos crescentes. O seu endpoint deve, portanto, ser idempotente: a mesma entrega pode chegar várias vezes, e o seu processamento deve produzir o mesmo resultado sem efeitos secundários.

Atenção : o seu endpoint deve responder em menos de 10 segundos com um código HTTP 2xx. Para além disso, ou em caso de código de erro, a entrega é considerada falhada e será repetida. Após falhas repetidas, o webhook é automaticamente desativado.

Boas práticas

• Verifique sempre a assinatura HMAC antes de processar um payload: nunca confie num pedido não autenticado.
• Responda depressa: devolva um 200 de imediato e depois processe a carga de trabalho em segundo plano. Evitará tempos de espera esgotados e repetições inúteis.
• Torne o seu processamento idempotente para absorver sem risco as entregas múltiplas.
• Filtre na origem: subscreva cada webhook apenas aos eventos úteis ao seu sistema destinatário.
• Vigie o contador de falhas e o histórico de entregas para detetar rapidamente um endpoint avariado antes de ser desativado.
• Utilize o botão Testar após cada alteração do seu lado (implementação, mudança de URL) para validar a cadeia sem esperar por um evento real.

Dica : combine os seus webhooks com os alertas e a configuração da sua equipa para encaminhar automaticamente a informação certa para o sistema certo. A disponibilidade dos webhooks depende da sua subscrição.