Webhook
Esecuzione dei test, logging, configurazione assistita da IA e analisi dei webhook.
Webhook
A cosa serve
- Esporre eventi interni (allarmi, attività, estrazioni) a sistemi esterni senza che debbano fare polling.
- Garantire la consegna con retry automatici e firma HMAC su ogni richiesta.
- Configurare un webhook senza scrivere codice grazie all'assistente IA.
Come funziona
Ogni evento interno innesca un POST verso l'URL registrato con un payload canonico e una firma X-Signature HMAC-SHA256. Se il destinatario restituisce 5xx/4xx, Rela ritenta con backoff esponenziale fino a 6 volte. Ogni tentativo viene loggato per il debugging.
Esecuzione dei Test
Prima di attivare un webhook in produzione, puoi eseguire un test manuale per verificare che l'endpoint di destinazione risponda correttamente:
POST /api/v1/integrations/webhooks/{webhook_id}/test
{
"sample_payload": { "event": "task.created", "task_id": "test_123" }
}Il test invia il payload all'endpoint configurato e restituisce il risultato:
| Campo | Descrizione |
|---|---|
status_code | Codice di risposta HTTP della destinazione |
response_body | Corpo della risposta (troncato a 1 KB) |
latency_ms | Tempo di risposta in millisecondi |
success | true se lo status e tra 200-299 |
Logging delle Consegne
Ogni consegna di webhook viene registrata con informazioni dettagliate per il debug:
| Campo | Tipo | Descrizione |
|---|---|---|
delivery_id | string | Identificatore univoco della consegna |
webhook_id | string | Webhook che ha originato la consegna |
event_type | string | Tipo di evento scatenante |
payload | object | Payload inviato |
status_code | int | Codice di risposta HTTP |
attempt | int | Numero del tentativo (1-5) |
latency_ms | int | Latenza della consegna |
created_at | datetime | Timestamp della consegna |
I log vengono conservati per 30 giorni e consultati tramite:
GET /api/v1/integrations/webhooks/{webhook_id}/deliveries?limit=50&skip=0Tentativi Automatici
Quando una consegna fallisce (status >= 400 o timeout), il sistema ritenta automaticamente:
| Tentativo | Ritardo |
|---|---|
| 1 | Immediato |
| 2 | 30 secondi |
| 3 | 5 minuti |
| 4 | 30 minuti |
| 5 | 2 ore |
Dopo il quinto tentativo fallito, il webhook viene contrassegnato come failing
e l'amministratore viene notificato. Non viene disattivato automaticamente.
Configurazione Assistita da IA
L'assistente IA puo suggerire configurazioni di webhook basandosi sulla descrizione del caso d'uso:
POST /api/v1/integrations/webhooks/ai-config
{
"description": "Notificare Slack quando un'attivita critica viene completata"
}Il sistema analizza la descrizione e suggerisce:
- Eventi a cui iscriversi
- Filtri raccomandati
- Formato del payload
- Header di autenticazione
L'utente rivede e approva la configurazione prima dell'attivazione.
Analisi dei Webhook
La dashboard di analisi mostra metriche aggregate per webhook:
- Tasso di successo — Percentuale di consegne riuscite (ultimi 7 giorni)
- Latenza media — Tempo medio di risposta della destinazione
- Consegne giornaliere — Volume di consegne nel periodo
- Errori frequenti — Top 5 codici di errore ricevuti
Le metriche vengono consultate tramite GET /api/v1/integrations/webhooks/{webhook_id}/analytics.
Benefici chiave
- Consegna garantita con retry automatici e backoff esponenziale.
- Firma HMAC-SHA256 perché il ricevente possa validare l'autenticità.
- Log per tentativo con body + risposta.
- Assistente IA per configurare URL ed eventi senza JSON manuale.
- Stesso motore per webhook interni (Rela → destinazione) e uscenti verso terze parti.