Webhook. Eventi in tempo reale, consegnati in modo affidabile.

Leggi il corpo della richiesta grezza come byte (prima di qualsiasi analisi JSON), calcola HMAC-SHA256 sui byte grezzi utilizzando il segreto condiviso del tuo endpoint, codifica in base16 (hex) il risultato e confrontalo con il valore nell'header X-Elido-Signature dopo aver rimosso il prefisso 'sha256='. Usa una funzione di confronto in tempo costante (ad es. hmac.compare_digest in Python, crypto.timingSafeEqual in Node.js) per prevenire attacchi di temporizzazione. Non confrontare mai la firma con un operatore di uguaglianza di stringhe standard. Esempi di codice per Node.js, Python e Go sono disponibili su /docs/guides/webhooks#verification.

Restituisci HTTP 200 (o qualsiasi codice di stato 2xx) entro 30 secondi. Il corpo della risposta viene ignorato - puoi restituire un corpo vuoto o { ok: true }. Se l'elaborazione richiede più di 30 secondi, restituisci immediatamente 200 ed elabora l'evento in modo asincrono (metti in coda a una coda interna, restituisci 200, elabora fuori dal percorso della richiesta). Restituire 4xx è trattato come 5xx ai fini del tentativo - entrambi attivano un nuovo tentativo. Restituisci 200 anche se l'evento non è pertinente per la tua integrazione (ad esempio, un evento link.created di cui non hai bisogno) per evitare tentativi spuri.

Ogni payload webhook include un campo event_id (UUID). Usa questo come chiave di idempotenza sul tuo ricevitore: se ricevi lo stesso event_id due volte (a causa di un tentativo dopo un fallimento parziale), elaboralo una sola volta. Memorizza gli ID degli eventi ricevuti in una tabella di deduplicazione con un TTL di almeno 72 ore (la finestra dei tentativi). Il payload del tentativo è identico all'originale - stesso event_id, stesso corpo - quindi un semplice controllo 'ho già visto questo event_id?' è sufficiente.

Gli endpoint vengono messi in pausa automaticamente dopo 30 fallimenti di consegna consecutivi (non-2xx o timeout). Questo impedisce a Elido di martellare indefinitamente un endpoint rotto. Risolvi il problema sottostante (solitamente: l'URL dell'endpoint è cambiato, il server è giù o il timeout di 30 secondi viene superato a causa di un'elaborazione lenta), quindi riprendi l'endpoint nella dashboard. Una volta ripreso, Elido non riproduce automaticamente gli eventi saltati durante la pausa - riproducili manualmente dal registro di consegna se hai bisogno di recuperarli.

Sì - abilita la modalità raw-click sull'endpoint. In modalità raw-click, Elido consegna gli eventi click.created individualmente senza finestra di batching, entro 2 secondi dal clic. Tieni presente che un workspace trafficato può produrre migliaia di eventi al minuto in modalità raw-click; assicurati che il tuo ricevitore possa gestire il throughput. Per la maggior parte dei casi d'uso di analytics, l'aggregazione batch predefinita di 5 secondi (fino a 100 clic per payload) è sufficiente e produce molte meno richieste HTTP.

I singoli payload degli eventi sono inferiori a 10KB. I payload dei clic in batch (modalità predefinita) possono contenere fino a 100 eventi per batch, con un limite totale della dimensione del payload di 100KB. Se un batch dovesse superare i 100KB, viene diviso automaticamente in più consegne. I campi di metadati di grandi dimensioni sui clic (ad es. URL referer lunghi) vengono troncati a 2KB per campo. Se il tuo ricevitore impone un limite rigoroso alla dimensione del payload, configura la modalità raw-click (un evento per consegna) invece della modalità batch.

Usa uno strumento come ngrok, Cloudflare Tunnel o localtunnel per esporre il tuo server locale con un URL HTTPS pubblico, quindi registra quell'URL come endpoint webhook nel tuo workspace di test. In alternativa, usa il pulsante di test del webhook nella dashboard per inviare un payload di esempio per qualsiasi tipo di evento a un endpoint registrato senza attivare un evento reale. Anche la CLI di Elido (elido webhook test --event click.created --endpoint https://...) funziona per test locali tramite script.

Gli eventi generati durante una finestra di manutenzione vengono messi in coda nel nostro flusso di eventi e consegnati al termine della finestra di manutenzione. La pagina di stato di Elido (status.elido.app) annuncia in anticipo le finestre di manutenzione pianificate. L'SLA di consegna dei webhook esclude le finestre di manutenzione annunciate. Per la tipica finestra di manutenzione di 30–60 minuti, la finestra di tentativo di 72 ore garantisce che nessun evento vada perso permanentemente - verranno consegnati nell'ordine in cui sono stati generati una volta che l'endpoint sarà di nuovo raggiungibile.