🌐 Webhooks
Os Webhooks da Kropie permitem enviar notificações e dados em tempo real para sistemas externos sempre que ocorre um evento relevante.
São ideais para automatizar alertas, integrar dados meteorológicos e agronómicos ou ligar a Kropie a ferramentas de terceiros.
Os webhooks permitem integrações diretas com plataformas como:
- Slack e Microsoft Teams
- Google Sheets e Excel Online
- Zapier, Make (Integromat) e n8n
- Sistemas próprios de gestão agrícola ou ERPs
❓ O que é um Webhook
Um webhook é uma requisição HTTP POST automática enviada pela Kropie para um URL definido por si, sempre que um determinado evento ocorre.
Essa requisição contém um payload em JSON com toda a informação necessária para que outro sistema possa reagir imediatamente.
📌 Exemplos de utilização
- Enviar uma mensagem para o Slack quando existe risco crítico de geada
- Criar uma linha numa Google Sheet quando uma estação fica offline
- Ativar um sistema de irrigação quando a precipitação ultrapassa um limite
- Receber atualizações automáticas de índices agronómicos
ℹ️ Webhooks permitem reagir a eventos em tempo real, sem necessidade de consultar a API continuamente.
🛠️ Configurar um Webhook
Para criar um novo webhook:
- Inicie sessão em app.kropie.com
- Aceda a Configurações → Integrações → Webhooks
- Clique em Criar Webhook
- Introduza o URL de destino (endpoint que irá receber os dados)
- Selecione os eventos a subscrever
- Confirme o formato dos dados (JSON)
- Clique em Guardar Webhook
O webhook fica ativo imediatamente e começa a enviar eventos assim que estes ocorram.
📣 Eventos suportados
A Kropie suporta vários tipos de eventos que podem ser associados a um webhook:
| Evento | Descrição |
|---|---|
| frost_risk_triggered | Alerta de risco de geada ativado |
| mildew_risk_triggered | Condições favoráveis ao míldio detetadas |
| heavy_rainfall | Precipitação acima de um limiar definido |
| station_offline | Estação deixou de comunicar |
| index_update | Recalculo de índices agronómicos |
| custom_alert_triggered | Alerta personalizado criado pelo utilizador |
Um único webhook pode subscrever um ou vários eventos.
📦 Exemplo de payload do Webhook
Cada evento é enviado como um objeto JSON estruturado.
{
"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"
}
}
ℹ️ Todos os timestamps são enviados em UTC (ISO 8601).
🔐 Segurança e validação
Para garantir a autenticidade e integridade das notificações:
- Cada requisição de webhook inclui um header de assinatura (
X-Kropie-Signature) - Utilize apenas endpoints com HTTPS
- Atualize a sua chave dos webhooks regularmente por segurança
- Evite export URLs publicamente sem qualquer controlo de acesso
📄 Exemplo de header de assinatura
X-Kropie-Signature: sha256=abcd1234ef567890...
🧪 Testar um Webhook
- Vá a Configurações → Integrações → Webhooks
- Selecione o webhook pretendido
- Clique em Enviar Evento de Teste
- Escolha o tipo de evento
- Confirme se o sistema externo recebe corretamente o payload
- Verifique se a resposta devolve 200 OK
✅ Requisitos de resposta
O endpoint que recebe o webhook deve:
- Responder com HTTP 200 OK
- Concluir a resposta em menos de 5 segundos
🔁 Reentrega automática
Se a entrega falhar:
- A Kropie tenta reenviar até 3 vezes
- Os reenvios utilizam atrasos progressivos
- Todas as falhas ficam registadas em Atividade de Webhooks
- É possível reativar manualmente entregas falhadas
💡 Boas práticas
- Utilize webhooks para eventos críticos, não para dados históricos
- Combine webhooks com a API para fluxos completos
- Registe logs do payload recebido para auditoria
- Valide sempre a assinatura do webhook
- Use um endpoint dedicado apenas para webhooks da Kropie
🔗 Casos de uso comuns
- Alertas automáticos de geada ou stress hídrico
- Integração com plataformas de automação
- Dashboards em tempo real
- Sistemas de irrigação inteligente
- Monitorização operacional de estações