Webhooks: subskrybuj zdarzenia linków i kliknięć

Webhooks przesyłają zdarzenia z Elido na Twój serwer gdy tylko się zdarzają. Używaj ich zamiast pollowania API, gdy potrzebujesz danych w czasie rzeczywistym — typowe przypadki użycia obejmują synchronizację metadanych linków z CRM, budowanie niestandardowego dashboardu lub uruchamianie pipeline CI gdy link zostaje opublikowany.

Dodaj endpoint webhook#

Dashboard → Webhooks → Nowy endpoint.
Wklej URL, na który powinniśmy wysyłać POST. Musi być HTTPS — odrzucamy zwykłe HTTP przy tworzeniu.
Wybierz typy zdarzeń, które chcesz. Pełna lista poniżej.
(Opcjonalnie) Wklej tajny klucz podpisywania lub pozwól nam go wygenerować. Sekret jest pokazywany raz; skopiuj go przed opuszczeniem strony.
Zapisz. Wysyłamy natychmiast zdarzenie testowe, żebyś mógł potwierdzić, że endpoint jest dostępny.

Katalog zdarzeń#

Aktualne typy zdarzeń. Nazwy mają format <zasób>.<akcja> i są stabilne między wersjami.

link.created — został utworzony nowy krótki link.
link.updated — zmieniono miejsce docelowe, slug, datę wygaśnięcia lub hasło.
link.deleted — link został usunięty w trybie soft (nadal można go przywrócić przez 30 dni).
link.clicked.aggregated — co 60 sekund wysyłamy liczniki kliknięć per link dla poprzedniego okna. Nie dostarczamy zdarzeń per kliknięcie przez webhooks (wolumen zmiażdżyłby większość endpointów) — użyj eksportu kliknięć dla surowych danych zdarzeń.
domain.verified — sprawdzenie DNS niestandardowej domeny przeszło pomyślnie.
domain.tls_renewed — Caddy odnowił certyfikat TLS dla niestandardowej domeny.
qr.generated — wyrenderowano SVG/PNG kodu QR.
abuse.flagged — nasz skaner URL oznaczył docelowy URL jako podejrzany.
member.invited / member.removed — zmiany członkostwa w workspace.

Kształt payloadu#

Każde zdarzenie ma tę samą kopertę:

{
  "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 jest unikalny per dostawa. Używaj go do idempotentności — jeśli otrzymasz ten sam id dwa razy (bo ponowiliśmy próbę), pomiń duplikat.

Weryfikacja podpisów#

Podpisujemy każde ciało webhooka za pomocą HMAC-SHA256 używając sekretu Twojego endpointu. Podpis jest w nagłówku Elido-Signature jako t=<unix_ts>,v1=<hex>.

Weryfikacja w 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;
}

Dołączamy timestamp do podpisanego payloadu, żeby zapobiegać replay. Odrzucaj zdarzenia gdzie |now - t| > 300 sekund.

Ponowne próby#

Ponawiamy nieudane dostawy (dowolna odpowiedź non-2xx lub brak odpowiedzi w ciągu 10 sekund) z wykładniczym backoffem: 30s, 1m, 5m, 30m, 2h, 12h. Po 6 niepowodzeniach oznaczamy endpoint jako failing i przestajemy ponawiać próbę dla tego konkretnego zdarzenia. Endpoint pozostaje subskrybowany; nowe zdarzenia nadal próbują dostawy.

Endpoint pozostaje failing przez 5 kolejnych dostaw → auto-wyłączamy go i wysyłamy e-mail do właściciela workspace. Ponownie włącz w dashboardzie po naprawieniu serwera.

Log dostaw#

Otwórz dowolny webhook w dashboardzie, aby zobaczyć ostatnie 500 dostaw z kodem statusu, czasem odpowiedzi i ciałem żądania/odpowiedzi dla każdej. Nieudane dostawy można odtworzyć ręcznie z tego widoku.

Lokalne testowanie#

Użyj Elido CLI, aby przekazywać webhooki na localhost:

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

CLI rejestruje tymczasowy endpoint, który działa do Ctrl-C, tuneluje dostawy na Twoją maszynę i drukuje ciało żądania dla każdego zdarzenia.

Limity#

20 endpointów na workspace (Pro), 100 (Business).
Maks. 10 KB rozmiar podpisanego payloadu. Większe payloady są dzielone — data zawiera flagę truncated: true i URL do pobrania pełnego ciała.
50 zdarzeń na sekundę utrzymanych per endpoint. Bursts są kolejkowane.

Rozwiązywanie problemów#

Endpoint zgłasza 401 w logu dostaw. Twój endpoint weryfikuje podpisy z błędnym sekretem. Porównaj sekret w Webhooks → Endpoint → Ustawienia z tym, który ma Twój serwer.

Niektóre zdarzenia przychodzą dwukrotnie. Albo ponowiliśmy próbę po powolnej odpowiedzi, albo Twój endpoint miał timeout bez odpowiadania. Użyj id zdarzenia do idempotentności.

Liczniki link.clicked.aggregated nie zgadzają się z dashboardem analitycznym. Dashboard jest w czasie rzeczywistym (w ciągu 30s od kliknięcia); webhook jest okienkowany na 60s. Istnieje też małe (~1%) rozbieżności, ponieważ boty filtrowane z dashboardu są nadal uwzględniane w surowych agregatach do czasu zamknięcia okna filtra botów.