Webhooks

I webhook collegano dAio ai vostri sistemi. Invece di interrogare la piattaforma in continuazione, lasciate che sia dAio ad avvisarvi: non appena si verifica un evento — un'allerta meteo attivata, un rischio elevato rilevato — dAio invia in tempo reale una richiesta HTTP firmata all'endpoint di vostra scelta. Automatizzate così i vostri flussi di lavoro: apertura di ticket, notifiche interne, aggiornamento di un cruscotto aziendale o attivazione di un piano d'azione sul campo.

È il ponte tra gli avvisi di dAio e il vostro sistema informativo.

Suggerimento : iniziate con un solo webhook abbonato a un unico tipo di evento, convalidate la catena dall'inizio alla fine, poi ampliate. Eviterete di sommergere i vostri sistemi di notifiche prima di aver reso affidabile l'elaborazione.

Configurare un webhook

1. Accedete a Impostazioni > Webhook.
2. Fate clic su Nuovo webhook.
3. Inserite l'URL di destinazione: l'endpoint HTTPS del vostro server (es. https://votre-serveur.com/webhook).
4. Selezionate gli eventi da ascoltare facendo clic sulle etichette corrispondenti.
5. Confermate con Crea.

Alla creazione viene generato automaticamente un segreto. Serve a firmare ogni richiesta con HMAC-SHA256 (vedere più avanti): conservatelo lato server, poiché vi permette di verificare che ogni chiamata provenga effettivamente da dAio.

Attenzione : l'URL deve essere in HTTPS e accessibile pubblicamente. Un endpoint in HTTP semplice o dietro un firewall chiuso non potrà ricevere le consegne.

Eventi disponibili

Evento	Descrizione
weather.alert	È stata attivata un'allerta meteo su un sito
weather.threshold	È stata superata una soglia meteo personalizzata
air_quality.alert	È stata emessa un'allerta sulla qualità dell'aria
pollen.alert	È stata emessa un'allerta pollini
marine.alert	È stata emessa un'allerta condizioni marine
frost.alert	È stata attivata un'allerta gelo
storm.alert	È stata attivata un'allerta temporale / tempesta
business.risk_high	È stato rilevato un livello di rischio elevato per la vostra attività

Suggerimento : abbonate ogni webhook solo agli eventi effettivamente utilizzati dal sistema destinatario. Un endpoint «ticket» non ha bisogno di ricevere gli stessi eventi di un endpoint «cruscotto».

Formato del payload

Ogni consegna è una richiesta POST il cui corpo è un oggetto JSON. La struttura generale è la seguente:

{
  "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)"
  }
}

Il campo event identifica il tipo di evento, timestamp indica la data di emissione (UTC, formato ISO 8601) e data contiene i dettagli specifici dell'evento.

Autenticazione HMAC-SHA256

Ogni richiesta è firmata con il vostro segreto tramite HMAC-SHA256. La firma è trasmessa nell'header X-Daio-Signature, nel formato sha256=<signature>.

Verificate sistematicamente questa firma prima di elaborare una richiesta: è ciò che garantisce che la chiamata provenga da dAio e che il payload non sia stato alterato.

Verifica lato server (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)

Attenzione : calcolate la firma sul corpo grezzo della richiesta (i byte ricevuti), prima di qualsiasi deserializzazione JSON. La minima riformattazione modifica l'hash e fa fallire la verifica.

Testare e fare il debug

• Fate clic sull'icona Testa (▶) accanto a un webhook per inviare un evento fittizio al vostro endpoint.
• Una risposta HTTP 2xx conferma che il vostro server ha ricevuto e accettato la richiesta.
• Espandete il webhook per consultare le sue ultime consegne: codice HTTP, tipo di evento e marca temporale.
• Un punto colorato indica lo stato del webhook: verde = attivo, rosso = disattivato dopo ripetuti fallimenti.

Cronologia delle consegne

Ogni invio viene registrato. Espandete un webhook per vedere, per ogni tentativo:

• Il codice HTTP di risposta (verde se < 300, rosso altrimenti)
• Il tipo di evento consegnato
• La data e l'ora del tentativo

Un contatore di fallimenti compare sul webhook quando alcune consegne sono fallite.

Tentativi e affidabilità

dAio ritenta automaticamente la consegna in caso di fallimento, con intervalli crescenti. Il vostro endpoint deve quindi essere idempotente: una stessa consegna può arrivare più volte, e la vostra elaborazione deve produrre lo stesso risultato senza effetti collaterali.

Attenzione : il vostro endpoint deve rispondere entro 10 secondi con un codice HTTP 2xx. Oltre tale soglia, o in caso di codice di errore, la consegna è considerata fallita e verrà ritentata. Dopo ripetuti fallimenti, il webhook viene disattivato automaticamente.

Buone pratiche

• Verificate sempre la firma HMAC prima di elaborare un payload: non fidatevi mai di una richiesta non autenticata.
• Rispondete in fretta: restituite un 200 immediatamente, poi elaborate il carico di lavoro in background. Eviterete timeout e ritentativi inutili.
• Rendete idempotente la vostra elaborazione per assorbire senza rischi le consegne multiple.
• Filtrate all'origine: abbonate ogni webhook solo agli eventi utili al suo sistema destinatario.
• Sorvegliate il contatore di fallimenti e la cronologia delle consegne per individuare rapidamente un endpoint guasto prima che venga disattivato.
• Usate il pulsante Testa dopo ogni modifica da parte vostra (deployment, cambio di URL) per convalidare la catena senza attendere un evento reale.

Suggerimento : abbinate i vostri webhook agli avvisi e alla configurazione del vostro team per instradare automaticamente l'informazione giusta verso il sistema giusto. La disponibilità dei webhook dipende dal vostro abbonamento.