Webhooki. Zdarzenia w czasie rzeczywistym, dostarczane niezawodnie.
Punkty końcowe webhooków dla poszczególnych obszarów roboczych odbierają zdarzenia dotyczące kliknięć, konwersji i zarządzania linkami z podpisami HMAC-SHA256. Automatyczne ponowne próby z wykładniczym czasem oczekiwania. Tryb SIEM przesyła zdarzenia strumieniowo do Twojej platformy bezpieczeństwa.
- 10+ typów zdarzeń - kliknięcia, konwersje, zmiany domen
- Podpis HMAC-SHA256 przy każdej dostawie
- 72-godzinne ponawianie z wykładniczym backoffem
- Dziennik dostaw z replayem jednym kliknięciem
Typy zdarzeń
10+ typów zdarzeń od ręki
Subskrybuj per endpoint - otrzymuj tylko zdarzenia, na których Ci zależy. Wysokowolumenowe zdarzenia kliknięć są domyślnie wysyłane w 5-sekundowym oknie batch; tryb raw-click dostarcza per kliknięcie dla przetwarzania strumieniowego.
- link.clicked
Każde kliknięcie redirectu. Tryb batch (okno 5 s) lub raw-click.
- link.created
W workspace utworzono nowy krótki link.
- link.updated
Zmieniono metadane, docelowy URL lub reguły linku.
- link.deleted
Link usunięty - zaktualizuj wszystkie zależne odniesienia.
- domain.verified
Domena niestandardowa przeszła weryfikację DNS.
- conversion.attributed
Zdarzenie przychodu powiązane z kliknięciem przez Stripe lub Shopify.
- campaign.completed
Kampania osiągnęła datę końcową lub limit kliknięć.
- member.invited
Dodano członka workspace’u lub provisionowano przez SCIM.
Plus link.expired, link.click_cap_reached, domain.ssl_issued i więcej - zobacz pełny katalog zdarzeń.
Gwarancje dostarczenia
Wykładniczy backoff. Okno 72 godzin.
Odpowiedź spoza 2xx lub 30-sekundowy timeout uruchamia automatyczne ponowienia: 30 s → 2 min → 10 min → 30 min → 2 h → 8 h → 24 h → 48 h. Po 72 godzinach dostarczenie jest oznaczane jako trwale nieudane i usuwane z kolejki - ale pozostaje w dzienniku dostaw do ręcznego replayu.
- 30-sekundowy timeout odpowiedziZwróć 200 natychmiast; przetwarzaj asynchronicznie, jeśli Twój handler jest wolny.
- 8 prób w 72 godzinachWykładniczy backoff - bez efektu lawiny przy restarcie.
- Auto-pauza po 30 kolejnych awariachAdmin workspace’u powiadomiony e-mailem. Wznów z panelu.
- Replay jednym kliknięciem z loguOryginalny payload, ten sam event_id - odbiorca musi być idempotentny.
| Zdarzenie | Endpoint | Status | Opóźnienie | Czas | |
|---|---|---|---|---|---|
link.clicked | api.acme.com/wh | 200 | 142ms | 14:04:31 | |
link.created | api.acme.com/wh | 200 | 88ms | 14:03:19 | |
conversion.attributed | logs.acme.com | 500 | 30001ms | 14:02:01 | |
domain.verified | api.acme.com/wh | 200 | 67ms | 13:58:44 | |
link.deleted | logs.acme.com | timeout | 30000ms | 13:55:12 |
Dziennik dostaw
Pełny dziennik. Filtruj, sprawdzaj, ponawiaj.
Każda próba jest logowana: ID zdarzenia, typ zdarzenia, URL endpointu, status HTTP, ciało odpowiedzi (do 4 KB) i opóźnienie. Retencja: 30 dni na Pro, 90 dni na Business.
- Filtruj po typie zdarzenia, endpoincie, statusie i zakresie dat
- Nieudane wpisy pokazują pełne ciało żądania do debugowania
- Replay wysyła oryginalny payload - ten sam event_id
- API: POST /v1/webhooks/deliveries/:id/replay
- Tryb SIEM: ustrukturyzowany JSON z gwarancją 7-dniowych ponowień
Co możesz zrobić
- Zdarzenia kliknięć, konwersji, linków i domen
- Podpisywanie żądań HMAC-SHA256
- Automatyczne ponowne próby - do 72 godzin
- Tryb SIEM do przesyłania zdarzeń bezpieczeństwa
- Filtrowanie tematów według typu zdarzenia
- Dziennik dostarczania webhooków z funkcją ponownego odtworzenia
Co dostarczają webhooki Elido i jak działa ich doręczanie
Webhooki są tak przydatne, jak ich niezawodność. Poniższe sekcje opisują gwarancje dostarczania, weryfikację podpisów, zachowanie podczas ponownych prób oraz tryb SIEM.
Zdarzenia kliknięć, konwersji, cyklu życia linków i domen - konfigurowalne dla każdego punktu końcowego
Każdy punkt końcowy webhooka może subskrybować jeden lub więcej typów zdarzeń: click.created (każde kliknięcie przekierowania), conversion.created (zdarzenie konwersji otrzymane ze Stripe, Shopify lub niestandardowego punktu końcowego), link.created, link.updated, link.deleted, link.expired, link.click_cap_reached, domain.verified, domain.ssl_issued, domain.ssl_error, workspace.member.added, workspace.member.removed. Zdarzenia kliknięć o dużym natężeniu mogą generować szum - domyślnie zdarzenia click.created są wysyłane z 5-sekundowym oknem agregacji (dostarczanie wsadowe, do 100 zdarzeń na pakiet). Jeśli potrzebujesz dostarczania w czasie rzeczywistym dla każdego kliknięcia (np. do zasilania procesora strumieniowego), włącz tryb raw-click w punkcie końcowym; pamiętaj, że może to generować tysiące żądań na minutę dla obciążonych obszarów roboczych i powinno być włączane tylko dla punktów końcowych, które poradzą sobie z taką przepustowością.
Każde żądanie jest podpisane za pomocą HMAC-SHA256 - zweryfikuj nagłówek X-Elido-Signature przed przetworzeniem
Elido podpisuje każde żądanie webhooka za pomocą HMAC-SHA256, używając wspólnego klucza (secret) skonfigurowanego w punkcie końcowym. Podpis jest dołączany do nagłówka X-Elido-Signature jako 'sha256=<hex_digest>'. Aby zweryfikować: oblicz HMAC-SHA256 dla surowej treści żądania przy użyciu wspólnego klucza, a następnie porównaj wynik z wartością nagłówka, korzystając z funkcji porównywania w czasie stałym (aby zapobiec atakom czasowym). Nigdy nie przetwarzaj ładunku webhooka przed weryfikacją podpisu. Klucz jest wyświetlany raz podczas tworzenia punktu końcowego; możesz go rotować w panelu sterowania z 15-minutowym oknem nakładania się (stary klucz pozostaje ważny przez 15 minut po wygenerowaniu nowego). Przykłady kodu weryfikacji podpisu w Node.js, Python i Go znajdują się w przewodniku po webhookach pod adresem /docs/guides/webhooks.
Automatyczne ponowne próby z wykładniczym czasem oczekiwania - do 72 godzin przed oznaczeniem dostarczenia jako nieudane
Jeśli punkt końcowy zwróci kod statusu inny niż 2xx lub upłynie limit czasu (30-sekundowy limit czasu odpowiedzi), Elido ponawia próbę dostarczenia z wykładniczym czasem oczekiwania: 30 sekund, 2 minuty, 10 minut, 30 minut, 2 godziny, 8 godzin, 24 godziny, 48 godzin. Po 72-godzinnym oknie dostarczenie zostaje trwale oznaczone jako nieudane i usunięte z kolejki ponownych prób. Nieudane dostarczenia pojawiają się w dzienniku dostarczania webhooków z końcowym kodem statusu HTTP (lub 'timeout'). Możesz odtworzyć dowolne nieudane dostarczenie z panelu sterowania lub API (POST /v1/webhooks/deliveries/:id/replay) - przydatne do odzyskiwania partii zdarzeń po awarii systemu odbiorczego. Punkty końcowe zwracające błąd 5xx przez ponad 30 kolejnych dostarczeń są automatycznie wstrzymywane, a administrator obszaru roboczego otrzymuje powiadomienie e-mail. Wznów działanie punktu końcowego w panelu sterowania po rozwiązaniu problemu.
Tryb SIEM przesyła zdarzenia audytu obszaru roboczego do Splunk, Datadog lub dowolnego punktu końcowego gromadzenia logów HTTPS
Tryb SIEM to specjalna konfiguracja webhooków do przesyłania zdarzeń bezpieczeństwa. Zamiast zdarzeń aplikacji (kliknięcia, konwersje), tryb SIEM dostarcza zdarzenia audytu obszaru roboczego: logowania SSO, nieudane próby logowania, tworzenie/rotacja/usuwanie kluczy API, zdarzenia aprowizacji SCIM, zmiany ról, rotacje kluczy webhooków i działania administratora (usuwanie linków, eksporty zbiorcze). Format ładunku to ustrukturyzowany JSON ze standardowym schematem (znacznik czasu, aktor, akcja, cel, ID obszaru roboczego, adres IP, user-agent) zaprojektowanym do przesyłania do popularnych platform SIEM. Webhooki SIEM mają gwarancję dostarczenia z 7-dniowym oknem ponownych prób i są podpisywane oddzielnie od webhooków aplikacji. Przetestowane integracje: Splunk HTTP Event Collector (HEC), Datadog Logs API, Elastic Logstash HTTP input oraz dowolny ogólny punkt końcowy logów HTTPS. Tryb SIEM jest funkcją dostępną tylko w planie Business.
Pełny dziennik dostarczania z treścią żądania, kodem odpowiedzi i odtwarzaniem nieudanych dostarczeń jednym kliknięciem
Każda próba dostarczenia webhooka jest rejestrowana: ID zdarzenia, typ zdarzenia, URL punktu końcowego, znacznik czasu dostarczenia, kod statusu HTTP, treść odpowiedzi (do 4 KB) i opóźnienie. Dziennik dostarczania można przeszukiwać według typu zdarzenia, punktu końcowego, zakresu dat i statusu (dostarczone, ponawianie, niepowodzenie). Nieudane dostarczenia zawierają pełną treść żądania, dzięki czemu można sprawdzić zdarzenie, które się nie powiodło, bez ponownego odtwarzania. Ponowne odtworzenie (Replay): POST /v1/webhooks/deliveries/:id/replay wysyła oryginalny ładunek (a nie nowe zdarzenie) do punktu końcowego - wymagana jest idempotentość po stronie odbiorcy. Przechowywanie dziennika dostarczania wynosi 30 dni w planie Pro i 90 dni w planie Business. W celu trwałego audytu zdarzeń webhooków skonfiguruj punkt końcowy SIEM lub włącz zaplanowany eksport dziennika audytu.
Zespoły inżynieryjne korzystające z webhooków Elido produkcyjnie
Nazwy są tymczasowe - prawdziwe studia przypadków klientów pojawią się tutaj po publikacji.
“Konsumujemy webhooki click.created w trybie wsadowym, aby zasilać nasz własny rurociąg analityczny. Weryfikacja podpisu HMAC i dziennik dostarczania z funkcją ponownego odtworzenia zaoszczędziły nam godziny debugowania podczas częściowej awarii - odtworzyliśmy partię pominiętych zdarzeń z panelu sterowania bez konieczności ponownego generowania zdarzenia ze źródła.”
“Tryb SIEM przesyłający zdarzenia audytu obszaru roboczego do naszego Splunk HEC był funkcją korporacyjną, której wymagał nasz zespół InfoSec. Zdarzenia logowania SSO i rotacje kluczy API w Splunk, z odpowiednim schematem, pozwoliły nam skorelować zdarzenia dostępu Elido z naszymi regułami alertów SIEM w ciągu jednego dnia od konfiguracji.”
“Webhooki link.expired uruchamiają nasz wewnętrzny przepływ pracy w celu aktualizacji bazy danych materiałów drukowanych - gdy link w kodzie QR wygasa, nasz zespół operacyjny automatycznie otrzymuje zadanie aktualizacji fizycznej etykiety. Zero ręcznego monitorowania stanów wygaśnięcia linków.”
Webhooki Elido vs Bitly vs Short.io
Ani Bitly, ani Short.io nie oferują wychodzących webhooków z podpisem HMAC i gwarancją ponownych prób. To porównanie szczerze opisuje tę lukę.
| Feature | Elido | Bitly | Short.io |
|---|---|---|---|
| Webhooki wychodzące | Tak - punkty końcowe dla każdego obszaru roboczego, subskrypcja dla każdego typu zdarzenia | Niedostępne | Tak - podstawowy webhook przy kliknięciu |
| Podpisywanie HMAC-SHA256 | Tak - każde dostarczenie podpisane, dostarczone przykłady kodu | Nie dotyczy | Częściowo - nagłówek podpisu obecny, brak dokumentacji |
| Automatyczne ponowne próby | Tak - wykładniczy czas oczekiwania, 72-godzinne okno | Nie dotyczy | Brak ponownych prób - wyślij i zapomnij |
| Dziennik dostarczania z funkcją odtwarzania | Tak - 30 dni Pro, 90 dni Business, odtwarzanie jednym kliknięciem | Nie dotyczy | Brak dziennika dostarczania |
| Tryb zdarzeń audytu SIEM | Tak - Business, ustrukturyzowany JSON do gromadzenia w SIEM | Niedostępne | Niedostępne |
| Automatyczne wstrzymanie punktu końcowego przy awarii | Tak - wstrzymanie po 30 kolejnych niepowodzeniach, powiadomienie admina | Nie dotyczy | Niedostępne |
| Typy zdarzeń | Kliknięcia, konwersje, cykl życia linku, domena, zdarzenia audytu | Nie dotyczy | Tylko kliknięcia |
Pytania o webhooki
Jak zweryfikować podpis HMAC-SHA256?
Odczytaj surową treść żądania jako bajty (przed jakimkolwiek parsowaniem JSON), oblicz HMAC-SHA256 na surowych bajtach przy użyciu wspólnego klucza punktu końcowego, zakoduj wynik w base16 (hex) i porównaj go z wartością w nagłówku X-Elido-Signature po usunięciu prefiksu 'sha256='. Użyj funkcji porównywania w czasie stałym (np. hmac.compare_digest w Pythonie, crypto.timingSafeEqual w Node.js), aby zapobiec atakom czasowym. Nigdy nie porównuj podpisu za pomocą standardowego operatora równości ciągów znaków. Przykłady kodu dla Node.js, Python i Go znajdują się pod adresem /docs/guides/webhooks#verification.
Co powinien zwracać mój odbiorca webhooka?
Zwróć HTTP 200 (lub dowolny kod statusu 2xx) w ciągu 30 sekund. Treść odpowiedzi jest ignorowana - możesz zwrócić pustą treść lub { ok: true }. Jeśli przetwarzanie trwa dłużej niż 30 sekund, zwróć 200 natychmiast i przetwarzaj zdarzenie asynchronicznie (dodaj do wewnętrznej kolejki, zwróć 200, przetwarzaj poza ścieżką żądania). Zwrócenie 4xx jest traktowane tak samo jak 5xx dla celów ponownych prób - oba wyzwalają ponowienie. Zwróć 200 nawet jeśli zdarzenie nie jest istotne dla Twojej integracji (np. zdarzenie link.created, którego nie potrzebujesz), aby uniknąć zbędnych ponownych prób.
Jak działa idempotentość dla zdarzeń webhooków?
Każdy ładunek webhooka zawiera pole event_id (UUID). Użyj go jako klucza idempotentości u swojego odbiorcy: jeśli otrzymasz to samo event_id dwukrotnie (z powodu ponowienia po częściowej awarii), przetwórz je tylko raz. Przechowuj otrzymane identyfikatory zdarzeń w tabeli deduplikacji z czasem wygaśnięcia (TTL) wynoszącym co najmniej 72 godziny (okno ponownych prób). Ładunek ponowienia jest identyczny z oryginałem - ten sam event_id, ta sama treść - więc proste sprawdzenie 'czy widziałem już to event_id?' jest wystarczające.
Dlaczego mój punkt końcowy jest automatycznie wstrzymywany?
Punkty końcowe są automatycznie wstrzymywane po 30 kolejnych niepowodzeniach dostarczenia (status inny niż 2xx lub limit czasu). Zapobiega to ciągłemu odpytywaniu uszkodzonego punktu końcowego przez Elido. Rozwiąż podstawowy problem (zwykle: zmiana adresu URL punktu końcowego, serwer nie działa lub przekroczono 30-sekundowy limit czasu z powodu powolnego przetwarzania), a następnie wznów działanie punktu końcowego w panelu sterowania. Po wznowieniu Elido nie odtwarza automatycznie zdarzeń, które zostały pominięte podczas wstrzymania - odtwórz je ręcznie z dziennika dostarczania, jeśli musisz je odzyskać.
Czy mogę otrzymywać zdarzenia kliknięć w czasie rzeczywistym dla każdego kliknięcia?
Tak - włącz tryb raw-click w punkcie końcowym. W trybie raw-click Elido dostarcza zdarzenia click.created indywidualnie bez okna wsadowego, w ciągu 2 sekund od kliknięcia. Pamiętaj, że obciążony obszar roboczy może generować tysiące zdarzeń na minutę w trybie raw-click; upewnij się, że Twój odbiorca poradzi sobie z taką przepustowością. W przypadku większości zastosowań analitycznych domyślna 5-sekundowa agregacja wsadowa (do 100 kliknięć na ładunek) jest wystarczająca i generuje znacznie mniej żądań HTTP.
Jaki jest limit rozmiaru ładunku dla zdarzeń webhooków?
Indywidualne ładunki zdarzeń mają poniżej 10 KB. Wsadowe ładunki kliknięć (tryb domyślny) mogą zawierać do 100 zdarzeń na partię, z całkowitym limitem rozmiaru ładunku wynoszącym 100 KB. Jeśli partia przekroczyłaby 100 KB, jest ona automatycznie dzielona na wiele dostarczeń. Duże pola metadanych przy kliknięciach (np. długie adresy URL referer) są skracane do 2 KB na pole. Jeśli Twój odbiorca narzuca ścisły limit rozmiaru ładunku, skonfiguruj tryb raw-click (jedno zdarzenie na dostarczenie) zamiast trybu wsadowego.
Czy istnieje sposób na lokalne przetestowanie webhooków podczas programowania?
Użyj narzędzia takiego jak ngrok, Cloudflare Tunnel lub localtunnel, aby udostępnić swój lokalny serwer pod publicznym adresem URL HTTPS, a następnie zarejestruj ten URL jako punkt końcowy webhooka w testowym obszarze roboczym. Alternatywnie użyj przycisku testowego wyzwalania webhooka w panelu sterowania, aby wysłać przykładowy ładunek dla dowolnego typu zdarzenia do zarejestrowanego punktu końcowego bez wyzwalania prawdziwego zdarzenia. Elido CLI (elido webhook test --event click.created --endpoint https://...) również sprawdza się w przypadku skryptowych testów lokalnych.
Co dzieje się ze zdarzeniami webhooków podczas zaplanowanego okna serwisowego?
Zdarzenia generowane podczas okna serwisowego są kolejkowane w naszym strumieniu zdarzeń i dostarczane po jego zakończeniu. Strona statusu Elido (status.elido.app) informuje o planowanych oknach serwisowych z wyprzedzeniem. SLA dostarczania webhooków nie obejmuje ogłoszonych okien serwisowych. W przypadku typowego 30–60 minutowego okna serwisowego, 72-godzinne okno ponownych prób oznacza, że żadne zdarzenia nie zostaną trwale utracone - zostaną one dostarczone w kolejności, w jakiej zostały wygenerowane, gdy tylko punkt końcowy będzie ponownie osiągalny.
Czytaj dalej
Synchroniczne uzupełnienie API dla asynchronicznych webhooków - twórz i zapytuj o linki programowo.
Odbieraj zdarzenia konwersji za pośrednictwem webhooków ze Stripe i Shopify - strona webhooków przychodzących.
Tryb SIEM dostarcza zdarzenia audytu obszaru roboczego - logowania SSO, aprowizacja SCIM, zmiany ról.
Zdarzenia kliknięć w Twoim magazynie analitycznym - alternatywa po stronie zapytań dla odbierania kliknięć przez webhook.
Gotowy, aby wypróbować?
Zacznij od planu darmowego, uaktualnij, gdy będziesz potrzebować niestandardowej domeny.