Webhooks: abonează-te la evenimente de linkuri și clicuri

Webhook-urile transmit evenimente de la Elido către serverul tău pe măsură ce se produc. Folosește-le în locul interogării repetate a API-ului atunci când ai nevoie de date în timp real — cazuri tipice de utilizare includ sincronizarea metadatelor linkurilor cu CRM-ul tău, construirea unui dashboard personalizat sau declanșarea unui pipeline CI când un link este publicat.

Adaugă un endpoint webhook

1. Dashboard → Webhooks → New endpoint.
2. Lipește URL-ul către care ar trebui să trimitem cereri POST. Trebuie să fie HTTPS — respingem HTTP simplu la creare.
3. Alege tipurile de evenimente dorite. Lista completă este mai jos.
4. (Opțional) Lipește un secret de semnare sau lasă-ne să generăm unul. Secretul este afișat o singură dată; copiază-l înainte de a părăsi pagina.
5. Save. Trimitem imediat un eveniment de test ca să confirmi că endpoint-ul este accesibil.

Catalog de evenimente

Tipurile de evenimente actuale. Numele urmează formatul <resource>.<action> și rămân stabile între versiuni.

• link.created — a fost creat un link scurt nou.
• link.updated — destinația, slug-ul, expirarea sau parola s-au modificat.
• link.deleted — linkul a fost șters în mod reversibil (poate fi recuperat timp de 30 de zile).
• link.clicked.aggregated — la fiecare 60 de secunde trimitem numărul de clicuri pe link pentru fereastra anterioară. Nu livrăm evenimente per clic prin webhook-uri (volumul ar copleși majoritatea endpoint-urilor) — folosește exportul de clicuri pentru date brute despre evenimente.
• domain.verified — verificarea DNS a unui domeniu personalizat a trecut.
• domain.tls_renewed — Caddy a reînnoit certificatul TLS pentru un domeniu personalizat.
• qr.generated — a fost randat un cod QR SVG/PNG.
• abuse.flagged — scanerul nostru de URL-uri a marcat o destinație ca fiind suspectă.
• member.invited / member.removed — modificări ale apartenenței la workspace.

Structura payload-ului

Fiecare eveniment are același plic:

{
  "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 este unic per livrare. Folosește-l pentru idempotență — dacă primești același id de două ori (pentru că am reîncercat), ignoră duplicatul.

Verificarea semnăturilor

Semnăm fiecare corp de webhook cu HMAC-SHA256 folosind secretul endpoint-ului tău. Semnătura se află în header-ul Elido-Signature sub forma t=<unix_ts>,v1=<hex>.

Pentru a verifica în 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;
}

Reîncercări

Reîncercăm livrările eșuate (orice răspuns non-2xx sau lipsa unui răspuns în 10 secunde) cu backoff exponențial: 30s, 1m, 5m, 30m, 2h, 12h. După 6 eșecuri marcăm endpoint-ul ca failing și oprim reîncercarea acelui eveniment specific. Endpoint-ul rămâne abonat; evenimentele noi continuă să încerce livrarea.

Dacă endpoint-ul rămâne failing timp de 5 livrări consecutive → îl dezactivăm automat și trimitem un email proprietarului workspace-ului. Reactivează-l din dashboard după ce ai reparat serverul.

Jurnal de livrări

Deschide orice webhook din dashboard pentru a vedea ultimele 500 de livrări, cu codul de stare, timpul de răspuns și corpul cererii/răspunsului pentru fiecare. Livrările eșuate pot fi reluate manual din această vizualizare.

Testare locală

Folosește CLI-ul Elido pentru a redirecționa webhook-uri către localhost:

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

CLI-ul înregistrează un endpoint temporar care durează până apeși Ctrl-C, tunelează livrările către mașina ta și afișează corpul cererii pentru fiecare eveniment.

Limite

• 20 de endpoint-uri per workspace (Pro), 100 (Business).
• Dimensiune maximă a payload-ului semnat de 10 KB. Payload-urile mai mari sunt împărțite — data include un flag truncated: true și un URL pentru a prelua corpul complet.
• 50 de evenimente pe secundă susținute per endpoint. Vârfurile sunt puse în coadă.

Depanare

Endpoint-ul raportează 401 în jurnalul de livrări. Endpoint-ul tău verifică semnăturile cu secretul greșit. Compară secretul din Webhooks → Endpoint → Settings cu cel stocat pe serverul tău.

Unele evenimente sosesc de două ori. Fie am reîncercat după un răspuns lent, fie endpoint-ul tău a expirat fără să răspundă. Folosește id-ul evenimentului pentru idempotență.

Numărătorile link.clicked.aggregated nu se potrivesc cu dashboard-ul de analiză. Dashboard-ul este în timp real (în interval de 30s de la clic); webhook-ul este agregat la 60s. Există și o mică discrepanță (~1%) deoarece boții filtrați din dashboard sunt totuși incluși în agregatele brute până când se închide fereastra de filtrare a boților.