Webhooks

Webhook-urile conectează dAio la propriile dvs. sisteme. În loc să interogați platforma în mod continuu, lăsați dAio să vă anunțe: de îndată ce are loc un eveniment — o alertă meteo declanșată, un risc ridicat detectat — dAio trimite în timp real o cerere HTTP semnată către endpoint-ul ales de dvs. Astfel vă automatizați fluxurile de lucru: deschiderea tichetelor, notificări interne, actualizarea unui tablou de bord operațional sau declanșarea unui plan de acțiune pe teren.

Este puntea dintre alertele dAio și sistemul dvs. informatic.

Sfat : începeți cu un singur webhook abonat la un singur tip de eveniment, validați lanțul de la cap la coadă, apoi extindeți. Veți evita să vă inundați sistemele cu notificări înainte de a fi fiabilizat procesarea.

Configurarea unui webhook

1. Accesați Setări > Webhook-uri.
2. Faceți clic pe Webhook nou.
3. Completați URL-ul de destinație: endpoint-ul HTTPS al serverului dvs. (ex. https://votre-serveur.com/webhook).
4. Selectați evenimentele de ascultat făcând clic pe etichetele corespunzătoare.
5. Validați cu Creare.

Un secret este generat automat la creare. Acesta servește la semnarea fiecărei cereri în HMAC-SHA256 (vezi mai jos): păstrați-l pe partea de server, vă permite să verificați că fiecare apel provine cu adevărat de la dAio.

Atenție : URL-ul trebuie să fie în HTTPS și accesibil public. Un endpoint în HTTP simplu sau în spatele unui firewall închis nu va putea primi livrările.

Evenimente disponibile

Eveniment	Descriere
weather.alert	A fost declanșată o alertă meteo pentru un sit
weather.threshold	A fost depășit un prag meteo personalizat
air_quality.alert	A fost emisă o alertă privind calitatea aerului
pollen.alert	A fost emisă o alertă de polen
marine.alert	A fost emisă o alertă privind condițiile marine
frost.alert	A fost declanșată o alertă de îngheț
storm.alert	A fost declanșată o alertă de furtună
business.risk_high	A fost detectat un nivel ridicat de risc pentru activitatea dvs.

Sfat : abonați fiecare webhook doar la evenimentele utilizate efectiv de sistemul destinatar. Un endpoint „tichete” nu are nevoie să primească aceleași evenimente ca un endpoint „tablou de bord”.

Formatul payload-ului

Fiecare livrare este o cerere POST al cărei corp este un obiect JSON. Structura generală este următoarea:

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

Câmpul event identifică tipul evenimentului, timestamp indică data emiterii (UTC, format ISO 8601), iar data conține detaliile specifice evenimentului.

Autentificare HMAC-SHA256

Fiecare cerere este semnată cu secretul dvs. prin HMAC-SHA256. Semnătura este transmisă în header-ul X-Daio-Signature, în formatul sha256=<signature>.

Verificați sistematic această semnătură înainte de a procesa o cerere: aceasta garantează că apelul provine de la dAio și că payload-ul nu a fost alterat.

Verificare pe partea de 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)

Atenție : calculați semnătura pe corpul brut al cererii (octeții primiți), înainte de orice deserializare JSON. Cea mai mică reformatare modifică hash-ul și face ca verificarea să eșueze.

Testare și depanare

• Faceți clic pe pictograma Testare (▶) din dreptul unui webhook pentru a trimite un eveniment fictiv către endpoint-ul dvs.
• Un răspuns HTTP 2xx confirmă că serverul dvs. a primit și a acceptat corect cererea.
• Desfășurați webhook-ul pentru a consulta ultimele sale livrări: cod HTTP, tip de eveniment și marcaj temporal.
• Un punct colorat indică starea webhook-ului: verde = activ, roșu = dezactivat după eșecuri repetate.

Istoricul livrărilor

Fiecare trimitere este jurnalizată. Desfășurați un webhook pentru a vedea, pentru fiecare tentativă:

• Codul HTTP de răspuns (verde dacă < 300, roșu în caz contrar)
• Tipul de eveniment livrat
• Data și ora tentativei

Un contor de eșecuri se afișează pe webhook atunci când unele livrări au eșuat.

Tentative și fiabilitate

dAio reîncearcă automat livrarea în caz de eșec, cu intervale crescătoare. Prin urmare, endpoint-ul dvs. trebuie să fie idempotent: aceeași livrare poate sosi de mai multe ori, iar procesarea dvs. trebuie să producă același rezultat fără efecte secundare.

Atenție : endpoint-ul dvs. trebuie să răspundă în mai puțin de 10 secunde cu un cod HTTP 2xx. Peste acest prag, sau în caz de cod de eroare, livrarea este considerată eșuată și va fi reîncercată. După eșecuri repetate, webhook-ul este dezactivat automat.

Bune practici

• Verificați întotdeauna semnătura HMAC înainte de a procesa un payload: nu acordați niciodată încredere unei cereri neautentificate.
• Răspundeți rapid: returnați imediat un 200, apoi procesați sarcina în fundal. Evitați expirările și reîncercările inutile.
• Faceți procesarea idempotentă pentru a absorbi fără risc livrările multiple.
• Filtrați la sursă: abonați fiecare webhook doar la evenimentele utile sistemului său destinatar.
• Monitorizați contorul de eșecuri și istoricul livrărilor pentru a detecta rapid un endpoint defect înainte de a fi dezactivat.
• Folosiți butonul Testare după fiecare modificare de partea dvs. (deployment, schimbare de URL) pentru a valida lanțul fără a aștepta un eveniment real.

Sfat : cuplați webhook-urile cu alertele și cu configurarea echipei dvs. pentru a direcționa automat informația potrivită către sistemul potrivit. Disponibilitatea webhook-urilor depinde de abonamentul dvs.