🌐 Webhooks

Os Webhooks permitem que a Kropie envie notificações e atualizações de dados em tempo real para outras plataformas automaticamente.
São ideais para utilizadores que querem integrar alertas ou medições da Kropie com ferramentas de terceiros, como Slack, Microsoft Teams, Google Sheets, ou serviços de automação como Zapier e n8n.

❓ O que é um Webhook

Um webhook é uma simples requisição HTTP POST que a Kropie envia para um URL à sua escolha sempre que ocorre um evento específico.
Ele entrega dados estruturados em JSON que podem ser processados por outra aplicação.

Exemplos:

Quando o risco de geada é detectado, enviar uma mensagem para um canal Slack.
Quando uma estação fica offline, criar uma entrada numa folha Google Sheet.
Quando a chuva excede um limite, ativar um alerta de irrigação num sistema personalizado.

🛠️ Configurar um Webhook

Faça login em app.kropie.com.
Vá a Configurações → Integrações → Webhooks.
Clique em Criar Webhook.
Insira o URL do Webhook para onde os dados devem ser enviados.
Selecione os eventos que deseja monitorizar (por exemplo, Frost Risk, Rainfall ou Station Offline).
Escolha o formato dos dados (JSON).
Clique em Guardar Webhook.

O seu webhook ficará ativo imediatamente e começará a enviar dados quando os eventos selecionados ocorrerem.

📣 Eventos Suportados

Evento	Descrição
frost_risk_triggered	Enviado quando um alerta de risco de geada é ativado.
mildew_risk_triggered	Enviado quando são detetadas condições de míldio.
heavy_rainfall	Enviado quando a precipitação excede um limite definido.
station_offline	Enviado quando uma estação deixa de transmitir dados.
index_update	Enviado quando novos valores de índices agronómicos são calculados.
custom_alert_triggered	Enviado para alertas criados pelo utilizador no dashboard.

É possível subscrever um ou múltiplos eventos por webhook.

📦 Exemplo de Payload do Webhook

{
  "event": "frost_risk_triggered",
  "timestamp": "2025-10-16T02:00:00Z",
  "station_id": "KRP001",
  "station_name": "Vineyard North",
  "location": {
    "latitude": 41.188,
    "longitude": -7.786
  },
  "data": {
    "temperature": -0.5,
    "humidity": 88,
    "dew_point": -1.1,
    "risk_level": "critical"
  }
}

🔐 Segurança

Para garantir a integridade dos webhooks:

Cada requisição de webhook inclui um header de assinatura que pode usar para verificar a autenticidade.
Utilize apenas URLs HTTPS.
Altere o segredo do webhook periodicamente.
Evite expor endpoints de webhook publicamente sem autenticação.

Exemplo de Header: X-Kropie-Signature: sha256=abcd1234ef567890...

🧪 Testar o Webhook

Pode testar a sua configuração antes da ativação:

Vá a Configurações → Integrações → Webhooks.
Clique em Enviar Evento de Teste.
Escolha um evento (por exemplo, frost_risk_triggered).
Verifique se o sistema externo recebe corretamente o payload JSON.
Confirme nos logs que recebeu uma resposta 200 OK.

✅ Requisitos de Resposta

O seu servidor ou aplicação deve devolver 200 OK em até 5 segundos.
Se o webhook falhar ou expirar:

A Kropie tenta entregar novamente até 3 vezes com atrasos crescentes.
As tentativas falhadas são registadas na seção Atividade de Webhooks.
Pode reiniciar manualmente qualquer entrega falhada.

❓ O que é um Webhook​

🛠️ Configurar um Webhook​

📣 Eventos Suportados​

📦 Exemplo de Payload do Webhook​

🔐 Segurança​

🧪 Testar o Webhook​

✅ Requisitos de Resposta​