Webhooks. Evenimente în timp real, livrate fiabil.

Citește corpul brut al cererii ca bytes (înainte de orice parsare JSON), calculează HMAC-SHA256 peste bytes-urile brute, folosind secretul partajat al endpoint-ului tău, codifică rezultatul base16 (hex) și compară-l cu valoarea din header-ul X-Elido-Signature, după eliminarea prefixului „sha256=”. Folosește o funcție de comparație cu timp constant (de ex., hmac.compare_digest în Python, crypto.timingSafeEqual în Node.js) pentru a preveni atacurile de tip timing. Nu compara niciodată semnătura cu un operator standard de egalitate de string-uri. Exemple de cod pentru Node.js, Python și Go se află la /docs/guides/webhooks#verification.

Returnează HTTP 200 (sau orice cod de stare 2xx) în cel mult 30 de secunde. Corpul răspunsului este ignorat - poți returna un corp vid sau { ok: true }. Dacă procesarea ta durează mai mult de 30 de secunde, returnează 200 imediat și procesează evenimentul asincron (pune-l în coadă internă, returnează 200, procesează în afara traseului cererii). Returnarea 4xx este tratată la fel ca 5xx în scopuri de reîncercare - amândouă declanșează o reîncercare. Returnează 200 chiar dacă evenimentul nu este relevant pentru integrarea ta (de ex., un eveniment link.created de care nu ai nevoie), pentru a evita reîncercări nejustificate.

Fiecare payload de webhook include un câmp event_id (UUID). Folosește-l ca cheie de idempotență pe receptorul tău: dacă primești același event_id de două ori (din cauza unei reîncercări după un eșec parțial), procesează-l o singură dată. Stochează ID-urile de eveniment primite într-un tabel de deduplicare, cu un TTL de cel puțin 72 de ore (fereastra de reîncercare). Payload-ul de reîncercare este identic cu cel original - același event_id, același corp - astfel încât o simplă verificare „am mai văzut acest event_id?” este suficientă.

Endpoint-urile sunt puse automat pe pauză după 30 de eșecuri de livrare consecutive (non-2xx sau timeout). Acest lucru previne bombardarea la nesfârșit a unui endpoint defect de către Elido. Remediază problema de bază (de obicei: URL-ul endpoint-ului s-a schimbat, serverul este indisponibil, sau timeout-ul de 30 de secunde este depășit din cauza procesării lente), apoi reactivează endpoint-ul din dashboard. Odată reactivat, Elido nu reface (replay) automat evenimentele omise pe durata pauzei - refă-le manual din jurnalul de livrare, dacă trebuie să recuperezi acele evenimente.

Da - activează modul raw-click pe endpoint. În modul raw-click, Elido livrează evenimente click.created individual, fără fereastră de agregare, în cel mult 2 secunde de la clic. Reține că un workspace activ poate produce mii de evenimente pe minut în modul raw-click; asigură-te că receptorul tău poate gestiona acest debit. Pentru majoritatea cazurilor de utilizare de analitice, agregarea implicită în batch de 5 secunde (până la 100 de clicuri per payload) este suficientă și produce mult mai puține cereri HTTP.

Payload-urile de evenimente individuale sunt sub 10KB. Payload-urile de clic în batch (mod implicit) pot avea până la 100 de evenimente per batch, cu un plafon total de dimensiune a payload-ului de 100KB. Dacă un batch ar depăși 100KB, este împărțit automat în mai multe livrări. Câmpurile de metadate mari de pe clicuri (de ex., URL-uri de referer lungi) sunt trunchiate la 2KB per câmp. Dacă receptorul tău impune o limită strictă de dimensiune a payload-ului, configurează modul raw-click (un eveniment per livrare), în loc de modul în batch.

Folosește un instrument precum ngrok, Cloudflare Tunnel sau localtunnel pentru a expune serverul tău local cu un URL HTTPS public, apoi înregistrează acel URL ca endpoint de webhook în workspace-ul tău de test. Alternativ, folosește butonul de test-fire pentru webhook-uri din dashboard, pentru a trimite un payload eșantion pentru orice tip de eveniment către un endpoint înregistrat, fără a declanșa un eveniment real. CLI-ul Elido (elido webhook test --event click.created --endpoint https://...) funcționează și el pentru testare locală scriptată.

Evenimentele generate în timpul unei ferestre de mentenanță sunt puse în coadă în fluxul nostru de evenimente și livrate după terminarea ferestrei de mentenanță. Pagina de status Elido (status.elido.app) anunță din timp ferestrele de mentenanță planificate. SLA-ul de livrare a webhook-urilor exclude ferestrele de mentenanță anunțate. Pentru fereastra tipică de mentenanță de 30–60 de minute, fereastra de reîncercare de 72 de ore înseamnă că niciun eveniment nu este pierdut definitiv - acestea sunt livrate în ordinea în care au fost generate, odată ce endpoint-ul devine din nou accesibil.