10 min czytaniaFunkcje

Webhooki zdarzeń linków: payloady, podpisy, ponowienia

Webhooki skracacza URL dla zdarzeń linków i kliknięć: koperta payloadu, click.created, podpisy X-Elido-Signature w Node i Pythonie, ponowienia.

Marius Voß
DevRel · edge infra

Webhooki skracacza URL Elido wysyłają POST z podpisaną kopertą JSON na Twój endpoint HTTPS, ilekroć w workspace'ie coś się zmieni: link zostanie utworzony, edytowany, usunięty, wygaśnie lub osiągnie limit kliknięć, zostanie zaproszony członek, domena przejdzie weryfikację. Każde żądanie niesie nagłówek X-Elido-Signature: v1=<hex>, czyli HMAC-SHA256 z {timestamp}.{raw_body}, a nieudana dostawa dostaje trzy próby w ciągu około dwudziestu minut.

Kliknięcia mają własne zdarzenie, click.created, z własnymi regułami: payload z ograniczoną ilością danych prywatnych, limit na endpoint i zgoda na ruch botów. Opisuje je ostatnia sekcja. Ten wpis to wychodząca połowa powierzchni API; szybki start API + SDK skracacza URL omawia połowę przychodzącą, a smart linki wyjaśnione to filarowy tekst o funkcjach, z których pochodzą zdarzenia linków.

Które zdarzenia linków wywołują dziś webhook

Każde poniższe zdarzenie trafia do endpointu webhooka, który zasubskrybował je po nazwie. Formularz nowego endpointu w panelu oferuje pola wyboru dla ośmiu najczęstszych; API przyjmuje dowolną nazwę z listy.

ZdarzenieWywoływane, gdyPole wyboru w panelu
link.createdLink zostanie utworzony, pojedynczo lub w imporcie zbiorczymtak
link.updatedZmieni się adres docelowy, ustawienia lub status, edycje zbiorcze, przywróceniatak
link.deletedLink zostanie usunięty, pojedynczo lub zbiorczotak
link.expiredLink przekroczy datę wygaśnięciatylko API
link.cap_reachedLink osiągnie maksymalną liczbę kliknięćtylko API
link.brokenKontrola uszkodzonych linków widzi, że cel zawodzitylko API
click.createdKliknięcie zostaje policzone (boty i skanery pomijane, chyba że endpoint się zgodzi)tak, nigdy zaznaczone domyślnie
workspace.created, workspace.updatedWorkspace zostanie utworzony lub zmienią się jego ustawieniatak
member.invited, member.removedCzłonek zostanie dodany (bezpośrednio, przez SCIM lub przyjęte zaproszenie) albo usuniętytak
member.role_changedZmieni się rola członkatylko API
invitation.created, invitation.acceptedZaproszenie zostanie wysłane lub przyjętetylko API
domain.verified, domain.ssl_failedDomena własna przejdzie kontrole DNS albo nadal ich nie przechodzi po 24 godzinachtylko API
audit.eventDowolny wpis w dzienniku audytutak

Linki szyfrowane dodają jeszcze dwa: link.encrypted_created i link.encryption_rotated. Jeśli wolisz nie aktualizować listy ręcznie, utwórz endpoint siem: dostaje wszystkie zdarzenia w workspace'ie, w tym wpisy audytu, bez żadnego filtra subskrypcji. Jedynym wyjątkiem jest click.created, które trafia tylko do endpointów event z zaznaczoną tą opcją.

Zdarzenia rozliczeniowe idą tą samą kolejką. Usługa billing publikuje subscription.created, subscription.activated, subscription.paused, subscription.resumed, subscription.frozen, subscription.unfrozen, subscription.change_scheduled, subscription.change_canceled, usage.threshold_80, usage.threshold_100 i usage.overage_charged. Endpoint siem odbiera je również.

W planach, jeszcze nie na żywo: filtry na endpoint, jak "tylko linki w folderze X". Do tego czasu filtruj po data.slug lub data.link_id w swoim handlerze.

Strona endpointu webhooka w Elido z dziennikiem dostaw pokazującym dostarczone zdarzenia, ponowioną dostawę i nieudaną z kodem statusu 503

Tworzenie endpointu webhooka przez API

Endpoint należy do jednego workspace'u. Tworzysz go przez POST na /v1/workspaces/{workspace_id}/webhooks:

curl -X POST "https://api.elido.app/v1/workspaces/$WORKSPACE_ID/webhooks" \
  -H "Authorization: Bearer elido_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/elido",
    "events": ["link.created", "link.updated", "link.deleted"],
    "description": "CRM sync",
    "kind": "event"
  }'

Odpowiedź to 201 z endpointem i, dla rodzajów event i siem, jednorazowym sekretem:

{
  "endpoint": {
    "id": 7,
    "workspace_id": 42,
    "url": "https://hooks.example.com/elido",
    "events": ["link.created", "link.updated", "link.deleted"],
    "is_active": true,
    "description": "CRM sync",
    "kind": "event",
    "config": {},
    "created_at": "2026-09-21T09:12:44Z"
  },
  "secret": "whsec_9f2c..."
}

Sekret generuje Elido; nie wysyłasz własnego. Skopiuj go teraz, bo żadne późniejsze wywołanie go nie zwraca. kind przyjmuje sześć wartości. event i siem to podpisane dostawy JSON, które omawia ten wpis. discord, telegram, slack i sentry przekształcają te same zdarzenia w wiadomość czatu lub zdarzenie Sentry, uwierzytelniają się przez URL lub zaszyfrowany token bota i nie niosą nagłówków HMAC.

Plany mają znaczenie przy tworzeniu. Endpoint event wymaga Pro, Business lub Enterprise, a workspace Free dostaje 402 Payment Required (panel otwiera zamiast tego okno z ofertą zmiany planu). Endpoint siem wymaga Business lub Enterprise. Kanały czatu i Sentry nie mają ograniczeń planu. Istniejące endpointy nadal dostarczają, jeśli workspace później obniży plan.

Uprawnienia: odczyt endpointów i dziennika dostaw wymaga workspace.view. Tworzenie, edycja, usuwanie, rotacja sekretu lub ponowna wysyłka dostawy wymaga workspace.edit, czyli administratora lub właściciela. Klucz API działa w workspace'ie, dla którego został wydany, i nigdy powyżej roli wybranej przy jego tworzeniu, więc klucz na poziomie viewera dostaje 403 na powyższy POST. Pełna dokumentacja: dokumentacja webhooków.

Koperta payloadu webhooka

Każda podpisana dostawa ma tę samą kopertę z czterema polami. data zawiera rekord, który się zmienił, więc dla zdarzeń linków to wiersz linku:

{
  "type": "link.created",
  "workspace_id": 42,
  "data": {
    "id": 91834,
    "workspace_id": 42,
    "domain_id": 3,
    "slug": "spring-sale",
    "destination_url": "https://shop.example.com/spring",
    "title": "Spring sale landing",
    "tags": ["newsletter"],
    "status": "active",
    "expires_at": null,
    "max_clicks": null,
    "redirect_status": 302,
    "created_by_user_id": 17,
    "created_at": "2026-09-21T09:14:02.184311Z"
  },
  "timestamp": "2026-09-21T09:14:02Z"
}

Ten przykład jest skrócony; prawdziwe data zawiera każdą kolumnę linku, w tym reguły targetowania, folder, kampanię i pola skanowania. W ciele nie ma ID zdarzenia ani short_url, więc jeśli go potrzebujesz, zbuduj krótki URL z domeny i slug. Zdarzenia zaplanowane wysyłają zamiast tego mniejszy obiekt: link.expired ma link_id, slug i destination_url, a link.cap_reached dodaje cap i clicks.

Jedna poprawka, o której powinieneś wiedzieć, jeśli logowałeś payloady przed poprawką redakcji: pola sekretne są teraz usuwane, zanim payload opuści Elido. password_hash linku chronionego hasłem i token zaproszenia pojawiały się kiedyś w data; już się nie pojawiają, ani w nowych dostawach, ani w dzienniku dostaw. Jeśli przechowywałeś stare payloady, warto te dane wyczyścić.

Weryfikacja nagłówka X-Elido-Signature

Każde podpisane żądanie niesie te nagłówki:

X-Elido-Signature: v1=5d8f0c3e...
X-Webhook-Signature: v1=5d8f0c3e...
X-Webhook-Timestamp: 1790068442
X-Webhook-Event: link.created
X-Webhook-Delivery: 55120
User-Agent: Elido-Webhooks/1.0

Oba nagłówki podpisu mają tę samą wartość, a X-Webhook-Signature to alias zgodności wstecznej. Elido oblicza HMAC-SHA256, zdefiniowany w RFC 2104, z całym ciągiem whsec_... jako kluczem, z znacznika czasu, kropki i surowych bajtów ciała. Skrót w hex dostaje prefiks v1=. W nagłówku nie ma pola t=; znacznik czasu mieszka we własnym nagłówku.

Przepływ weryfikacji podpisu: nagłówki X-Elido-Signature i X-Webhook-Timestamp oraz surowe ciało i sekret zasilają HMAC-SHA256 z ts kropka body, porównywany w stałym czasie jako v1= hex, a potem bramka świeżości 5 minut po stronie odbiorcy rozdziela na przetworzenie zdarzenia lub odrzucenie z 400

W Node podpisuj surowe bajty, a nie ponownie zserializowany obiekt. Z tego powodu Express potrzebuje na tej trasie express.raw({ type: "application/json" }):

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyElido(secret, headers, rawBody, toleranceSec = 300) {
  const ts = headers["x-webhook-timestamp"] ?? "";
  if (!/^\d+$/.test(ts)) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false;

  const mac = createHmac("sha256", secret).update(`${ts}.`).update(rawBody);
  const expected = Buffer.from("v1=" + mac.digest("hex"));

  // During a rotation the old secret signs X-Elido-Signature-Previous.
  return ["x-elido-signature", "x-elido-signature-previous"].some((name) => {
    const got = Buffer.from(headers[name] ?? "");
    return got.length === expected.length && timingSafeEqual(got, expected);
  });
}

Sprawdzenie długości ma znaczenie: timingSafeEqual w Node rzuca wyjątek dla buforów o różnych rozmiarach, zamiast zwracać false. Wersja w Pythonie ze standardowym modułem hmac:

import hashlib
import hmac
import time


def verify_elido(secret: str, headers, raw_body: bytes, tolerance: int = 300) -> bool:
    ts = headers.get("X-Webhook-Timestamp", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > tolerance:
        return False
    digest = hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256)
    expected = "v1=" + digest.hexdigest()
    for name in ("X-Elido-Signature", "X-Elido-Signature-Previous"):
        got = headers.get(name)
        if got and hmac.compare_digest(got, expected):
            return True
    return False

Jeśli sprawdzenie ciągle zawodzi, poradnik weryfikacji podpisów webhooków ma wersję w Go, węzeł Code w n8n i typowe przyczyny niezgodności. Pięciominutowe okno to Twoja kontrola, nie nasza. Elido nadaje świeży znacznik czasu każdej próbie, także ponowieniom, więc prawidłowe ponowienie nigdy nie wygląda na przestarzałe. Bez okna każdy, kto przechwycił jedno żądanie, mógłby odtworzyć je za tydzień i podpis nadal by pasował.

Rotacja to POST /v1/workspaces/{workspace_id}/webhooks/{id}/rotate-secret albo przycisk Rotate na stronie endpointu. Nowy sekret dostajesz raz. Przez kolejne siedem dni każda dostawa niesie też X-Elido-Signature-Previous, podpisany starym sekretem, dlatego obie powyższe funkcje go próbują. Wdróż nowy sekret w dowolnym momencie tego tygodnia i nic się nie wywróci.

Polityka ponowień webhooków

Worker dostaw odbiera oczekujące dostawy co kilka sekund, więc zmiana linku zwykle dociera do Ciebie w ciągu sekund. Każda odpowiedź 2xx oznacza dostawę jako zakończoną. Status inny niż 2xx, błąd sieci lub brak odpowiedzi w ciągu 10 sekund liczy się jako nieudana próba.

Wykres słupkowy harmonogramu ponowień webhooka: próba 1 w T+0, próba 2 pięć minut po niepowodzeniu w T+5m, próba 3 piętnaście minut później w T+20m, potem dostawa jest oznaczana jako nieudana i nie ma już automatycznych prób, dopóki ktoś nie kliknie Retry lub nie wywoła endpointu retry

Trzy próby na dostawę, dwadzieścia minut od początku do końca. To celowo krótko i szczerze mówiąc krócej, niż wybrałbym dla odbiorcy za niestabilnym VPN-em. Dwugodzinna awaria po Twojej stronie nie zostanie pokryta automatycznymi ponowieniami. Pokrywa ją dziennik dostaw: GET /v1/workspaces/{workspace_id}/webhooks/{id}/deliveries wylicza każdą dostawę ze statusem, kodem HTTP, opóźnieniem, liczbą prób i czasem następnego ponowienia, a strona endpointu pokazuje te same wiersze z przyciskiem Retry. Retry, czyli POST .../deliveries/{delivery_id}/retry, ponownie uzbraja nieudaną lub dostarczoną dostawę ze świeżym budżetem trzech prób i zwraca 202. Dostawa wciąż oczekująca dostaje 409.

Niektóre niepowodzenia pomijają ponowienia. Endpoint Telegram bez chat_id albo nieprawidłowy DSN Sentry jest oznaczany jako nieudany od razu, bo powtarzanie żądania nie naprawi konfiguracji. Aby wyłączyć endpoint bez usuwania, wyślij PUT z "is_active": false; wstrzymane endpointy nie dostają nowych dostaw.

Jeśli Twój handler wykonuje ciężką pracę, najpierw zwróć 200, a zadanie zakolejkuj. Dziesięciosekundowy limit to miejsce, w którym wolny, ale udany handler zamienia się w duplikat, co prowadzi nas do deduplikacji.

Planujesz odbiorcę dla swojego zespołu? Strona funkcji webhooków pokazuje stronę panelu tego wszystkiego.

Idempotencja i kolejność webhooków

Elido dostarcza co najmniej raz. Sekcja o ponowieniach pokazała jeden sposób powstania duplikatu: Twój handler zatwierdza pracę, potem nie mieści się w dziesięciosekundowym oknie, a Elido wysyła ją ponownie. Ręczny Retry wysyła ponownie celowo.

Oba przypadki zachowują tę samą wartość X-Webhook-Delivery, bo jest to ID jednej dostawy do jednego endpointu, a nie jednej próby. Klucz opieraj na niej:

CREATE TABLE elido_webhook_seen (
  delivery_id BIGINT PRIMARY KEY,
  received_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- in the handler, inside the same transaction as your work:
INSERT INTO elido_webhook_seen (delivery_id) VALUES ($1)
ON CONFLICT (delivery_id) DO NOTHING
RETURNING delivery_id;
-- no row back means you've already handled this delivery

Dwa endpointy zasubskrybowane na to samo zdarzenie dostają dwa różne ID dostaw, więc deduplikuj per endpoint. Przy rzadkich restartach po naszej stronie zdarzenie może trafić do kolejki dwa razy jako osobne dostawy; jeśli podwójny zapis by zaszkodził, dodaj drugą zaporę na type plus data.id plus data.updated_at.

Nie ma obietnicy kolejności. Dostawy wychodzą od najstarszej wymagalnej, ale ponowienie wcześniejszego zdarzenia może dotrzeć po późniejszym. Porównaj data.updated_at z tym, co masz zapisane, zanim nadpiszesz link, i nie opieraj kolejności na timestamp koperty: ma tylko precyzję jednej sekundy.

Webhook click.created

click.created wysyła jedną podpisaną dostawę na każde policzone kliknięcie. Nie leży na ścieżce przekierowania: przekierowanie publikuje kliknięcie i idzie dalej, co wyjaśnia wpis fire-and-forget click ingestion, a zdarzenie jest budowane później z zapisanego kliknięcia. Spodziewaj się kilku sekund między kliknięciem a POST-em, nie milisekund.

Obiekt data wygląda tak:

{
  "type": "click.created",
  "workspace_id": 42,
  "timestamp": "2026-11-12T10:04:31Z",
  "data": {
    "id": "clk_3_99120",
    "link_id": 9183,
    "workspace_id": 42,
    "slug": "spring",
    "host": "go.acme.example",
    "short_url": "https://go.acme.example/spring",
    "timestamp": "2026-11-12T10:04:29Z",
    "country": "DE",
    "device": "mobile",
    "browser": "Safari",
    "referer_host": "news.ycombinator.com",
    "ip": "203.0.113.0",
    "is_bot": false,
    "is_scanner": false
  }
}

Kilka reguł kształtuje to, co dociera:

  • Prywatność przede wszystkim. Payload jest budowany po zastosowaniu ustawień prywatności analityki workspace'u. IP jest zawsze tylko skróconą siecią (/24 dla IPv4, /48 dla IPv6), a w trybie bez danych osobowych jest pomijane w całości. Referrer jest przycięty do hosta; ścieżki i ciągi zapytania nigdy nie wychodzą.
  • Boty są domyślnie wyłączone. Kliknięcia oznaczone is_bot lub is_scanner (skaner bezpieczeństwa poczty pobierający link z wyprzedzeniem) są pomijane, chyba że zaznaczysz w endpoincie "Include bot and scanner clicks" albo wyślesz przez API config.include_bot_clicks: true. Znane roboty indeksujące i boty podglądu linków nigdy nie liczą się jako kliknięcia, więc nigdy nie są wysyłane.
  • Limit, nie kolejka. Każdy endpoint dostaje najwyżej 50 zdarzeń kliknięć na sekundę. Nadwyżka jest odrzucana, a nie opóźniana, więc wirusowy link nie zasypie Twojego odbiornika, ale też webhook nie jest kompletną księgą w szczycie. Jeśli liczy się każde kliknięcie, uzgodnij dane z API analityki.
  • Deduplikuj po data.id. Dostawa jest at-least-once jak każde inne zdarzenie. data.id pozostaje takie samo, jeśli kliknięcie zostanie przetworzone dwa razy, a X-Webhook-Delivery obejmuje ponowienia jednej dostawy.
  • Te same ponowienia i podpis. Trzy próby (teraz, +5 minut, +15 minut) i sprawdzanie X-Elido-Signature z wcześniejszej części tego wpisu.

click.created dostają tylko endpointy event, które je zaznaczą. Formularz w panelu je wyświetla, ale nigdy nie zaznacza domyślnie, a endpointy Discord, Telegram, Sentry i siem go nie otrzymują. Zapier (Catch Hook w Webhooks by Zapier), Make (Custom webhook) i n8n (węzeł Webhook) mogą je przyjąć jako wyzwalacz.

Dwie inne drogi nadal mają sens dla danych o kliknięciach. Forwardery zdarzeń zamieniają każde kliknięcie w zdarzenie po stronie serwera w narzędziu, którego już używasz: Zdarzenia kliknięć w Mixpanel, Zdarzenia kliknięć Klaviyo w profilach albo Metryki przekierowań linków w Datadog dla paneli operacyjnych. A API analityki, GET /v1/analytics/workspaces/{workspace_id}/clicks/recent oraz eksport clicks.csv, to pełny zapis. Webhooki vs polling dla śledzenia kliknięć omawiają, która pasuje.

Przeczytaj tekst filarowy: smart linki wyjaśnione.

Powiązane na blogu

Najczęściej zadawane pytania

Czy Elido wysyła webhook dla każdego kliknięcia w link?

Tak, przez zdarzenie click.created: jedna podpisana dostawa na każde policzone kliknięcie, kilka sekund po jego wystąpieniu. Kliknięcia botów i skanerów bezpieczeństwa są pomijane, chyba że endpoint się na nie zgodzi, a każdy endpoint ma limit 50 zdarzeń kliknięć na sekundę, przy czym nadwyżka jest odrzucana, a nie kolejkowana. Dla pełnego zapisu wirusowego linku czytaj też API analityki.

Jak zweryfikować podpis webhooka Elido?

Oblicz HMAC-SHA256 z wartości X-Webhook-Timestamp, kropki i surowego ciała żądania, z kluczem w postaci sekretu whsec_. Zakoduj wynik w hex, dodaj prefiks v1= i porównaj w stałym czasie z nagłówkiem X-Elido-Signature. Odrzucaj znaczniki czasu starsze niż pięć minut.

Ile razy Elido ponawia nieudany webhook?

Każda dostawa ma trzy próby: jedną od razu, drugą pięć minut po niepowodzeniu i trzecią piętnaście minut później. Każdy status inny niż 2xx, błąd sieci lub odpowiedź wolniejsza niż dziesięć sekund liczy się jako niepowodzenie. Po trzeciej próbie dostawa jest oznaczona jako nieudana, dopóki nie klikniesz Retry.

Jaka jest różnica między X-Elido-Signature a X-Webhook-Signature?

Żadna poza nazwą. Oba nagłówki niosą ten sam podpis v1=. X-Elido-Signature jest podstawowy, a X-Webhook-Signature zachowano jako alias zgodności wstecznej, więc w nowym kodzie używaj pierwszego. Podczas rotacji sekretu Elido wysyła przez siedem dni także X-Elido-Signature-Previous, podpisany starym sekretem.

Jak uniknąć dwukrotnego przetworzenia tego samego webhooka?

Zapisuj wartość nagłówka X-Webhook-Delivery i pomijaj każde żądanie, którego wartość już obsłużyłeś. Identyfikuje ona jedną dostawę do jednego endpointu i pozostaje taka sama przy automatycznych ponowieniach i ręcznych ponownych wysyłkach, więc wystarczy unikalny indeks na niej.

Kto może tworzyć lub usuwać webhooki w workspace'ie?

Administratorzy i właściciele workspace'u. Listowanie endpointów i odczyt dziennika dostaw wymaga dostępu do podglądu; tworzenie, edycja, usuwanie, rotacja sekretu lub ponowna wysyłka dostawy wymaga uprawnienia workspace.edit. Klucze API są ograniczone do roli wybranej przy tworzeniu klucza.

Wypróbuj Elido

Wklej URL, otrzymaj krótki link

Bez rejestracji. Link działa 30 dni. Zarejestruj się, aby zachować go na zawsze.

Wymagane darmowe konto. Darmowy plan zawiera łącznie 25 linków. Masz już konto? Zaloguj się

Wypróbuj Elido

Skracarka URL hostowana w UE: własne domeny, głęboka analityka i otwarte API. Darmowy plan - bez karty kredytowej.

Tagi
url shortener webhooks
link click webhook
webhook signature verification
webhook retry policy
webhook idempotency
webhook payload

Czytaj dalej