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

1. Dashboard → Webhook → Nuovo endpoint.
2. Incolla l'URL a cui dobbiamo inviare POST. Deve essere HTTPS — rifiutiamo l'HTTP semplice al momento della creazione.
3. Scegli i tipi di evento che vuoi. L'elenco completo è qui sotto.
4. (Opzionale) Incolla un segreto di firma, o lascia che ne generiamo uno. Il segreto viene mostrato una volta; copialo prima di lasciare la pagina.
5. 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;
}

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.