Webhook: iscriviti agli eventi di link e clic

I webhook inviano eventi da Elido al tuo server non appena accadono. Usali invece di fare polling all'API quando hai bisogno di dati in tempo reale — i casi d'uso tipici includono la sincronizzazione dei metadati dei link con il tuo CRM, la costruzione di una dashboard personalizzata, o l'avvio di una pipeline CI quando un link viene pubblicato.

Aggiungi un endpoint webhook#

Dashboard → Webhook → Nuovo endpoint.
Incolla l'URL a cui dobbiamo inviare POST. Deve essere HTTPS — rifiutiamo l'HTTP semplice al momento della creazione.
Scegli i tipi di evento che vuoi. L'elenco completo è qui sotto.
(Opzionale) Incolla un segreto di firma, o lascia che ne generiamo uno. Il segreto viene mostrato una volta; copialo prima di lasciare la pagina.
Salva. Inviamo immediatamente un evento di test per confermare che l'endpoint sia raggiungibile.

Catalogo degli eventi#

I tipi di evento attuali. I nomi seguono <risorsa>.<azione> e rimangono stabili tra le versioni.

link.created — è stato creato un nuovo link abbreviato.
link.updated — destinazione, slug, scadenza o password modificati.
link.deleted — il link è stato eliminato in modo soft (ancora recuperabile per 30 giorni).
link.clicked.aggregated — ogni 60 secondi inviamo i conteggi dei clic per link per la finestra precedente. Non consegniamo eventi per singolo clic tramite webhook (il volume schiaccerebbe la maggior parte degli endpoint) — usa l'esportazione clic per i dati grezzi degli eventi.
domain.verified — il controllo DNS di un dominio personalizzato è passato.
domain.tls_renewed — Caddy ha rinnovato il certificato TLS per un dominio personalizzato.
qr.generated — è stato reso un SVG/PNG di un codice QR.
abuse.flagged — il nostro scanner URL ha contrassegnato una destinazione come sospetta.
member.invited / member.removed — modifiche all'appartenenza al workspace.

Struttura del payload#

Ogni evento ha lo stesso envelope:

{
  "id": "evt_2c8L9N4M5",
  "type": "link.created",
  "created_at": "2026-05-15T09:42:11.382Z",
  "workspace_id": 4123,
  "data": {
    "link_id": 891234,
    "slug": "spring-2026",
    "destination": "https://acme.com/spring-sale",
    "created_by": "user_5821"
  }
}

id è unico per consegna. Usalo per l'idempotenza — se ricevi lo stesso id due volte (perché abbiamo fatto retry), salta il duplicato.

Verifica delle firme#

Firmiamo ogni corpo del webhook con HMAC-SHA256 usando il segreto del tuo endpoint. La firma è nell'intestazione Elido-Signature come t=<unix_ts>,v1=<hex>.

Per verificare in Node:

import { createHmac } from "node:crypto";

function verify(secret: string, body: string, header: string): boolean {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=")),
  );
  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${body}`)
    .digest("hex");
  return expected === parts.v1;
}

Includiamo il timestamp nel payload firmato per prevenire i replay. Rifiuta gli eventi dove |now - t| > 300 secondi.

Retry#

Ritentiamo le consegne fallite (qualsiasi risposta non-2xx, o nessuna risposta entro 10 secondi) con backoff esponenziale: 30s, 1m, 5m, 30m, 2h, 12h. Dopo 6 fallimenti contrassegniamo l'endpoint come failing e smettiamo di riprovare quell'evento specifico. L'endpoint rimane iscritto; i nuovi eventi continuano a tentare la consegna.

L'endpoint rimane failing per 5 consegne consecutive → lo disabilitiamo automaticamente e inviamo un'email al proprietario del workspace. Riabilita nella dashboard una volta che hai risolto il problema sul tuo server.

Log delle consegne#

Apri qualsiasi webhook nella dashboard per vedere le ultime 500 consegne, con codice di stato, tempo di risposta e corpo di richiesta/risposta per ognuna. Le consegne fallite possono essere riprodotte manualmente da questa vista.

Test in locale#

Usa il Elido CLI per inoltrare i webhook al localhost:

npx @elido/cli webhooks forward --url http://localhost:3000/webhooks

Il CLI registra un endpoint temporaneo che dura finché non premi Ctrl-C, fa il tunnel delle consegne alla tua macchina e stampa il corpo della richiesta per ogni evento.

Limiti#

20 endpoint per workspace (Pro), 100 (Business).
Dimensione massima del payload firmato di 10 KB. I payload più grandi vengono suddivisi — data include un flag truncated: true e un URL per recuperare il corpo completo.
50 eventi al secondo sostenuti per endpoint. I burst vengono messi in coda.

Risoluzione dei problemi#

L'endpoint riporta 401 nel log delle consegne. Il tuo endpoint sta verificando le firme con il segreto errato. Confronta il segreto in Webhook → Endpoint → Impostazioni con quello che il tuo server ha memorizzato.

Alcuni eventi arrivano due volte. O abbiamo riprovato dopo una risposta lenta, o il tuo endpoint è andato in timeout senza rispondere. Usa l'id dell'evento per l'idempotenza.

I conteggi di link.clicked.aggregated non corrispondono alla dashboard delle analisi. La dashboard è in tempo reale (entro 30s dal clic); il webhook è a finestre da 60s. C'è anche una piccola discrepanza (~1%) perché i bot filtrati dalla dashboard sono ancora inclusi negli aggregati grezzi finché la finestra del filtro bot non si chiude.