Webhook. Real-time events, delivered reliably.
Gli endpoint webhook per workspace ricevono eventi di clic, conversione e gestione dei link con firme HMAC-SHA256. Tentativi automatici con backoff esponenziale. La modalità SIEM trasmette gli eventi alla tua piattaforma di sicurezza.
- 10+ event types — clicks, conversions, domain changes
- HMAC-SHA256 signature on every delivery
- 72-hour exponential-backoff retry
- Delivery log with one-click replay
Event types
10+ event types out of the box
Subscribe per endpoint — receive only the events you care about. High-volume click events ship in a 5-second batched window by default; raw-click mode delivers per-click for stream processors.
- link.clicked
Every redirect click. Batched (5s window) or raw-click mode.
- link.created
A new short link was created in the workspace.
- link.updated
Link metadata, target URL, or rules changed.
- link.deleted
Link removed — update any downstream references.
- domain.verified
Custom domain passed DNS verification.
- conversion.attributed
Revenue event matched to a click via Stripe or Shopify.
- campaign.completed
Campaign reached its end date or click cap.
- member.invited
Workspace member added or SCIM-provisioned.
Plus link.expired, link.click_cap_reached, domain.ssl_issued, and more — see the full event catalog.
Delivery guarantees
Exponential backoff. 72-hour window.
A non-2xx response or a 30-second timeout triggers automatic retries: 30 s → 2 min → 10 min → 30 min → 2 h → 8 h → 24 h → 48 h. After 72 hours the delivery is permanently failed and removed from the queue — but still in the delivery log for manual replay.
- 30-second response timeoutReturn 200 immediately; process async if your handler is slow.
- 8 retry attempts over 72 hoursExponential backoff — no avalanche effect on restart.
- Auto-pause after 30 consecutive failuresWorkspace admin notified by email. Resume from dashboard.
- One-click replay from logOriginal payload, same event_id — receiver must be idempotent.
| Event | Endpoint | Status | Latency | Time | |
|---|---|---|---|---|---|
link.clicked | api.acme.com/wh | 200 | 142ms | 14:04:31 | |
link.created | api.acme.com/wh | 200 | 88ms | 14:03:19 | |
conversion.attributed | logs.acme.com | 500 | 30001ms | 14:02:01 | |
domain.verified | api.acme.com/wh | 200 | 67ms | 13:58:44 | |
link.deleted | logs.acme.com | timeout | 30000ms | 13:55:12 |
Delivery log
Full log. Filter, inspect, replay.
Every attempt is logged: event ID, event type, endpoint URL, HTTP status, response body (up to 4 KB), and latency. Retention is 30 days on Pro, 90 days on Business.
- Filter by event type, endpoint, status, and date range
- Failed entries show full request body for debugging
- Replay sends original payload — same event_id
- API: POST /v1/webhooks/deliveries/:id/replay
- SIEM mode: structured JSON with 7-day retry guarantee
What you can do
- Eventi di clic, conversione, link e dominio
- Firma delle richieste HMAC-SHA256
- Tentativi automatici — fino a 72 ore
- Modalità SIEM per l'inoltro degli eventi di sicurezza
- Filtraggio dei topic per tipo di evento
- Registro di consegna dei webhook con replay
Cosa consegnano i webhook di Elido e come funziona la consegna
I webhook sono utili solo quanto la loro affidabilità. Le sezioni seguenti coprono le garanzie di consegna, la verifica della firma, il comportamento dei tentativi e la modalità SIEM.
Eventi di clic, conversione, ciclo di vita del link e dominio — configurabili per endpoint
Ogni endpoint webhook può iscriversi a uno o più tipi di evento: click.created (ogni clic di reindirizzamento), conversion.created (evento di conversione ricevuto da Stripe, Shopify o endpoint personalizzato), link.created, link.updated, link.deleted, link.expired, link.click_cap_reached, domain.verified, domain.ssl_issued, domain.ssl_error, workspace.member.added, workspace.member.removed. Gli eventi di clic ad alto volume possono essere rumorosi — per impostazione predefinita, i webhook click.created vengono inviati con una finestra di aggregazione di 5 secondi (consegna in batch, fino a 100 eventi per payload). Se hai bisogno di una consegna in tempo reale per singolo clic (ad esempio, per alimentare uno stream processor), abilita la modalità raw-click sull'endpoint; tieni presente che questo può produrre migliaia di richieste al minuto per i workspace trafficati e dovrebbe essere abilitato solo per gli endpoint in grado di gestire tale throughput.
Ogni richiesta è firmata con HMAC-SHA256 — verifica l'header X-Elido-Signature prima di elaborare
Elido firma ogni corpo della richiesta webhook con HMAC-SHA256 utilizzando il segreto condiviso configurato sull'endpoint. La firma è inclusa nell'header X-Elido-Signature come 'sha256=<hex_digest>'. Per verificare: calcola HMAC-SHA256 sul corpo grezzo della richiesta utilizzando il segreto condiviso, confronta il risultato con il valore dell'header utilizzando una funzione di confronto in tempo costante (per prevenire attacchi di temporizzazione). Non elaborare mai un payload webhook prima di aver verificato la firma. Il segreto viene mostrato una sola volta alla creazione dell'endpoint; ruotalo nella dashboard con una finestra di sovrapposizione a tempo zero (il vecchio segreto rimane valido per 15 minuti dopo la generazione di uno nuovo). Esempi di codice per la verifica della firma in Node.js, Python e Go sono disponibili nella guida ai webhook su /docs/guides/webhooks.
Tentativi automatici con backoff esponenziale — fino a 72 ore prima che una consegna sia segnata come fallita
Se un endpoint restituisce un codice di stato non-2xx o va in timeout (timeout della risposta di 30 secondi), Elido riprova la consegna con backoff esponenziale: 30 secondi, 2 minuti, 10 minuti, 30 minuti, 2 ore, 8 ore, 24 ore, 48 ore. Dopo la finestra di 72 ore, la consegna viene contrassegnata come fallita permanentemente e rimossa dalla coda dei tentativi. Le consegne fallite appaiono nel registro di consegna dei webhook con il codice di stato HTTP finale (o 'timeout'). Puoi riprodurre qualsiasi consegna fallita dalla dashboard o tramite API (POST /v1/webhooks/deliveries/:id/replay) — utile per recuperare un batch di eventi dopo un'interruzione a valle. Gli endpoint che restituiscono 5xx per più di 30 consegne consecutive vengono messi in pausa automaticamente e l'amministratore del workspace viene informato via email. Riprendi l'endpoint dalla dashboard una volta risolto il problema sottostante.
La modalità SIEM trasmette gli eventi di audit del workspace a Splunk, Datadog o qualsiasi endpoint di ingestione log HTTPS
La modalità SIEM è una configurazione speciale dei webhook per l'inoltro degli eventi di sicurezza. Invece degli eventi applicativi (clic, conversioni), la modalità SIEM consegna gli eventi di audit del workspace: accessi SSO, accessi falliti, creazione/rotazione/eliminazione di chiavi API, eventi di provisioning SCIM, modifiche dei ruoli, rotazioni dei segreti dei webhook e azioni amministrative (eliminazione di link, esportazioni massive). Il formato del payload è JSON strutturato con uno schema standard (timestamp, attore, azione, target, workspace_id, indirizzo IP, user agent) progettato per l'ingestione nelle comuni piattaforme SIEM. I webhook SIEM hanno una consegna garantita con tentativi fino a 7 giorni e sono firmati separatamente dai webhook applicativi. Integrazioni testate: Splunk HTTP Event Collector (HEC), Datadog Logs API, input HTTP di Elastic Logstash e qualsiasi endpoint log HTTPS generico. La modalità SIEM è una funzionalità esclusiva per i piani Business.
Registro di consegna completo con corpo della richiesta, codice di risposta e replay con un clic per le consegne fallite
Ogni tentativo di consegna dei webhook viene registrato: ID evento, tipo di evento, URL dell'endpoint, timestamp di consegna, codice di stato HTTP, corpo della risposta (fino a 4KB) e latenza. Il registro di consegna è interrogabile per tipo di evento, endpoint, intervallo di date e stato (consegnato, in fase di riprovo, fallito). Le consegne fallite includono il corpo completo della richiesta in modo da poter ispezionare l'evento che ha fallito senza riprodurlo. Replay: POST /v1/webhooks/deliveries/:id/replay invia il payload originale (non un nuovo evento) all'endpoint — è richiesta l'idempotenza sul tuo ricevitore. La conservazione del registro di consegna è di 30 giorni nel piano Pro, 90 giorni nel piano Business. Per un audit permanente degli eventi webhook, configura un endpoint SIEM o abilita l'esportazione pianificata del registro di audit.
Team di ingegneria che utilizzano i webhook di Elido in produzione
I nomi sono segnaposto — i casi di studio reali dei clienti verranno pubblicati qui man mano che vengono prodotti.
“Consumiamo i webhook click.created in modalità batch per alimentare la nostra pipeline di analytics. La verifica della firma HMAC e il registro di consegna con replay ci hanno risparmiato ore di debug durante un'interruzione parziale — abbiamo riprodotto il batch di eventi mancanti dalla dashboard senza ricostruire l'evento dalla sorgente.”
“La modalità SIEM che trasmette gli eventi di audit del workspace al nostro Splunk HEC era la funzionalità enterprise richiesta dal nostro team InfoSec. Gli eventi di accesso SSO e le rotazioni delle chiavi API in Splunk, con lo schema corretto, ci hanno permesso di correlare gli eventi di accesso di Elido con le nostre regole di avviso SIEM entro un giorno dalla configurazione.”
“I webhook link.expired attivano il nostro workflow interno per aggiornare il database dei materiali stampati — quando un link di un codice QR scade, il nostro team operativo riceve un'attività automatica per aggiornare l'etichetta fisica. Zero monitoraggio manuale degli stati di scadenza dei link.”
Webhook di Elido vs Bitly vs Short.io
Né Bitly né Short.io offrono webhook in uscita con firma HMAC e garanzie di tentativo. Questo confronto è sincero riguardo al divario.
| Feature | Elido | Bitly | Short.io |
|---|---|---|---|
| Webhook in uscita | Sì — endpoint per workspace, iscrizione per tipo di evento | Non disponibile | Sì — webhook di base sul clic |
| Firma HMAC-SHA256 | Sì — ogni consegna firmata, esempi di codice forniti | Non applicabile | Parziale — header della firma presente, non documentato |
| Tentativi automatici | Sì — backoff esponenziale, finestra di 72 ore | Non applicabile | Nessun tentativo — fire and forget |
| Registro di consegna con replay | Sì — 30 giorni Pro, 90 giorni Business, replay con un clic | Non applicabile | Nessun registro di consegna |
| Modalità eventi di audit SIEM | Sì — Business, JSON strutturato per ingestione SIEM | Non disponibile | Non disponibile |
| Auto-pausa dell'endpoint in caso di errore | Sì — in pausa dopo 30 fallimenti consecutivi, amministratore notificato | Non applicabile | Non disponibile |
| Tipi di eventi | Clic, conversione, ciclo di vita del link, dominio, eventi di audit | Non applicabile | Solo clic |
Domande sui webhook
Come posso verificare la firma HMAC-SHA256?
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.
Cosa dovrebbe restituire il mio ricevitore webhook?
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.
Come funziona l'idempotenza per gli eventi webhook?
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.
Perché il mio endpoint viene messo in pausa automaticamente?
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.
Posso ricevere eventi di clic in tempo reale per ogni singolo clic?
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.
Qual è il limite di dimensione del payload per gli eventi webhook?
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.
Esiste un modo per testare i webhook localmente durante lo sviluppo?
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.
Cosa succede agli eventi webhook durante una finestra di manutenzione pianificata?
Gli eventi generati durante una finestra di manutenzione vengono messi in coda in Redpanda 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.
Keep reading
Il complemento API sincrono ai webhook asincroni — crea e interroga i link a livello di programmazione.
Ricevi eventi di conversione tramite webhook da Stripe e Shopify — il lato webhook in entrata.
La modalità SIEM consegna gli eventi di audit del workspace — accessi SSO, provisioning SCIM, modifiche dei ruoli.
Eventi di clic in ClickHouse — l'alternativa lato query alla ricezione dei clic tramite webhook.
Pronto a provarlo?
Inizia con il piano gratuito, effettua l'upgrade quando hai bisogno di un dominio personalizzato.