Вебхуки. Real-time events, delivered reliably.
Кінцеві точки вебхуків для кожного робочого простору отримують події кліків, конверсій та керування посиланнями з підписами HMAC-SHA256. Автоматичні повторні спроби з експоненціальною витримкою. Режим SIEM передає події на вашу платформу безпеки.
- 10+ event types — clicks, conversions, domain changes
- HMAC-SHA256 signature on every delivery
- 72-hour exponential-backoff retry
- Delivery log with one-click replay
Event types
10+ event types out of the box
Subscribe per endpoint — receive only the events you care about. High-volume click events ship in a 5-second batched window by default; raw-click mode delivers per-click for stream processors.
- link.clicked
Every redirect click. Batched (5s window) or raw-click mode.
- link.created
A new short link was created in the workspace.
- link.updated
Link metadata, target URL, or rules changed.
- link.deleted
Link removed — update any downstream references.
- domain.verified
Custom domain passed DNS verification.
- conversion.attributed
Revenue event matched to a click via Stripe or Shopify.
- campaign.completed
Campaign reached its end date or click cap.
- member.invited
Workspace member added or SCIM-provisioned.
Plus link.expired, link.click_cap_reached, domain.ssl_issued, and more — see the full event catalog.
Delivery guarantees
Exponential backoff. 72-hour window.
A non-2xx response or a 30-second timeout triggers automatic retries: 30 s → 2 min → 10 min → 30 min → 2 h → 8 h → 24 h → 48 h. After 72 hours the delivery is permanently failed and removed from the queue — but still in the delivery log for manual replay.
- 30-second response timeoutReturn 200 immediately; process async if your handler is slow.
- 8 retry attempts over 72 hoursExponential backoff — no avalanche effect on restart.
- Auto-pause after 30 consecutive failuresWorkspace admin notified by email. Resume from dashboard.
- One-click replay from logOriginal payload, same event_id — receiver must be idempotent.
| Event | Endpoint | Status | Latency | Time | |
|---|---|---|---|---|---|
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 |
Delivery log
Full log. Filter, inspect, replay.
Every attempt is logged: event ID, event type, endpoint URL, HTTP status, response body (up to 4 KB), and latency. Retention is 30 days on Pro, 90 days on Business.
- Filter by event type, endpoint, status, and date range
- Failed entries show full request body for debugging
- Replay sends original payload — same event_id
- API: POST /v1/webhooks/deliveries/:id/replay
- SIEM mode: structured JSON with 7-day retry guarantee
What you can do
- Події кліків, конверсій, посилань та доменів
- Підписування запитів за допомогою HMAC-SHA256
- Автоматичні повторні спроби — до 72 годин
- Режим SIEM для пересилання подій безпеки
- Фільтрація топіків за типом події
- Журнал доставки вебхуків із можливістю повторного відправлення
Що доставляють вебхуки Elido та як працює доставка
Вебхуки корисні лише за умови їхньої надійності. Розділи нижче охоплюють гарантії доставки, перевірку підпису, поведінку під час повторних спроб та режим SIEM.
Події кліків, конверсій, життєвого циклу посилань та доменів — налаштовуються для кожної кінцевої точки
Кожна кінцева точка вебхука може підписатися на один або кілька типів подій: click.created (кожен клік перенаправлення), conversion.created (подія конверсії, отримана від Stripe, Shopify або спеціальної кінцевої точки), 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. Великий обсяг подій кліків може створювати шум — за замовчуванням вебхуки click.created надсилаються з 5-секундним вікном агрегації (пакетна доставка, до 100 подій у корисному навантаженні). Якщо вам потрібна доставка кожного кліка в реальному часі (наприклад, для потокового процесора), увімкніть режим raw-click для кінцевої точки; зауважте, що це може генерувати тисячі запитів за хвилину для активних робочих просторів, тому цей режим варто вмикати лише для кінцевих точок, здатних обробити таку пропускну здатність.
Кожен запит підписаний HMAC-SHA256 — перевірте заголовок X-Elido-Signature перед обробкою
Elido підписує тіло кожного запиту вебхука за допомогою HMAC-SHA256, використовуючи спільний секрет, налаштований для кінцевої точки. Підпис міститься в заголовку X-Elido-Signature у форматі 'sha256=<hex_digest>'. Для перевірки: обчисліть HMAC-SHA256 для сирого тіла запиту, використовуючи спільний секрет, і порівняйте результат зі значенням заголовка за допомогою функції порівняння за сталий час (щоб запобігти атакам за часом). Ніколи не обробляйте корисне навантаження вебхука без перевірки підпису. Секрет показується лише один раз під час створення кінцевої точки; змінюйте його на панелі керування з вікном перекриття без простоїв (старий секрет залишається дійсним протягом 15 хвилин після створення нового). Приклади коду для перевірки підпису на Node.js, Python та Go доступні в посібнику з вебхуків за адресою /docs/guides/webhooks.
Автоматичні повторні спроби з експоненціальною витримкою — до 72 годин, перш ніж доставка буде позначена як невдала
Якщо кінцева точка повертає код статусу, відмінний від 2xx, або стається таймаут (30-секундний таймаут відповіді), Elido повторює доставку з експоненціальною витримкою: 30 секунд, 2 хвилини, 10 хвилин, 30 хвилин, 2 години, 8 годин, 24 години, 48 годин. Після 72-годинного вікна доставка позначається як остаточно невдала та видаляється з черги повторних спроб. Невдалі доставки з'являються в журналі доставки вебхуків із остаточним кодом статусу HTTP (або 'timeout'). Ви можете повторно відправити будь-яку невдалу доставку з панелі керування або через API (POST /v1/webhooks/deliveries/:id/replay) — це корисно для відновлення пакету подій після збою в роботі системи. Кінцеві точки, які повертають 5xx для більш ніж 30 послідовних доставок, автоматично призупиняються, а адміністратор робочого простору отримує повідомлення електронною поштою. Відновіть роботу кінцевої точки на панелі керування після усунення причини проблеми.
Режим SIEM передає події аудиту робочого простору в Splunk, Datadog або будь-яку кінцеву точку прийому логів через HTTPS
Режим SIEM — це спеціальна конфігурація вебхуків для пересилання подій безпеки. Замість подій програми (кліки, конверсії), режим SIEM доставляє події аудиту робочого простору: входи через SSO, невдалі спроби входу, створення/зміна/видалення ключів API, події ініціалізації SCIM, зміни ролей, ротація секретів вебхуків та дії адміністратора (видалення посилань, масовий експорт). Формат корисного навантаження — структурований JSON зі стандартною схемою (timestamp, actor, action, target, workspace_id, ip_address, user_agent), розробленою для прийому в поширені платформи SIEM. Вебхуки SIEM мають гарантовану доставку з вікном повторних спроб до 7 днів і підписуються окремо від прикладних вебхуків. Перевірені інтеграції: Splunk HTTP Event Collector (HEC), Datadog Logs API, вхід Elastic Logstash HTTP та будь-яка загальна кінцева точка логів HTTPS. Режим SIEM доступний лише в плані Business.
Повний журнал доставки з тілом запиту, кодом відповіді та повторним відправленням невдалих доставок в один клік
Кожна спроба доставки вебхука логується: ID події, тип події, URL кінцевої точки, мітка часу доставки, код статусу HTTP, тіло відповіді (до 4 КБ) та затримка. У журналі доставки можна здійснювати пошук за типом події, кінцевою точкою, діапазоном дат і статусом (доставлено, повторна спроба, невдало). Невдалі доставки містять повне тіло запиту, тому ви можете переглянути подію, яка не була доставлена, без повторного відправлення. Повторне відправлення: POST /v1/webhooks/deliveries/:id/replay надсилає оригінальне корисне навантаження (а не нову подію) на кінцеву точку — для цього потрібна ідемпотентність вашого приймача. Термін зберігання журналу доставки становить 30 днів для Pro та 90 днів для Business. Для постійного аудиту подій вебхуків налаштуйте кінцеву точку SIEM або увімкніть запланований експорт журналу аудиту.
Інженерні команди, які використовують вебхуки Elido у продакшені
Імена є плейсхолдерами — реальні кейси клієнтів з'являться тут після публікації.
“Ми споживаємо вебхуки click.created у пакетному режимі для наповнення нашого власного конвеєра аналітики. Перевірка підпису HMAC та журнал доставки з можливістю повторного відправлення заощадили нам години на налагодженні під час часткового збою — ми повторно відправили пакет пропущених подій із панелі керування, не відновлюючи їх із джерела.”
“Передача подій аудиту робочого простору в наш Splunk HEC за допомогою режиму SIEM була саме тією функцією корпоративного рівня, якої потребувала наша команда InfoSec. Події входу через SSO та ротація ключів API у Splunk зі правильною схемою дозволили нам зіставити події доступу Elido з нашими правилами сповіщень SIEM протягом одного дня після налаштування.”
“Вебхуки link.expired запускають наш внутрішній робочий процес для оновлення бази даних друкованих матеріалів — коли посилання з QR-кодом закінчується, наша операційна команда автоматично отримує завдання оновити фізичну етикетку. Жодного ручного моніторингу станів закінчення терміну дії посилань.”
Вебхуки Elido проти Bitly та Short.io
Ні Bitly, ні Short.io не пропонують вихідні вебхуки з підписом HMAC та гарантіями повторних спроб. Це порівняння чесно вказує на цю різницю.
| Feature | Elido | Bitly | Short.io |
|---|---|---|---|
| Вихідні вебхуки | Так — кінцеві точки для кожного робочого простору, підписка за типом подій | Недоступно | Так — базовий вебхук за кліком |
| Підписування HMAC-SHA256 | Так — кожна доставка події підписана, надаються приклади коду | Не застосовується | Частково — заголовок підпису присутній, але не задокументований |
| Автоматичні повторні спроби | Так — експоненціальна витримка, вікно 72 години | Не застосовується | Без повторних спроб — надіслав і забув |
| Журнал доставки з повторним відправленням | Так — 30 днів Pro, 90 днів Business, повторне відправлення в один клік | Не застосовується | Без журналу доставки |
| Режим подій аудиту SIEM | Так — Business, структурований JSON для прийому в SIEM | Недоступно | Недоступно |
| Автоматичне призупинення кінцевої точки в разі помилки | Так — призупиняється після 30 послідовних помилок, адміністратор отримує сповіщення | Не застосовується | Недоступно |
| Типи подій | Кліки, конверсії, життєвий цикл посилань, домени, події аудиту | Не застосовується | Тільки кліки |
Питання про вебхуки
Як перевірити підпис HMAC-SHA256?
Зчитайте сире тіло запиту як байти (до будь-якого парсингу JSON), обчисліть HMAC-SHA256 для цих байтів, використовуючи спільний секрет вашої кінцевої точки, закодуйте результат у base16 (hex) і порівняйте його зі значенням у заголовку X-Elido-Signature, видаливши префікс 'sha256='. Використовуйте функцію порівняння за сталий час (наприклад, hmac.compare_digest у Python, crypto.timingSafeEqual у Node.js), щоб запобігти атакам за часом. Ніколи не порівнюйте підпис за допомогою стандартного оператора рівності рядків. Приклади коду для Node.js, Python та Go доступні за адресою /docs/guides/webhooks#verification.
Що повинен повертати мій приймач вебхуків?
Поверніть HTTP 200 (або будь-який код статусу 2xx) протягом 30 секунд. Тіло відповіді ігнорується — ви можете повернути порожнє тіло або { ok: true }. Якщо ваша обробка триває довше 30 секунд, негайно поверніть 200 і обробляйте подію асинхронно (помістіть у внутрішню чергу, поверніть 200, обробляйте поза шляхом запиту). Повернення 4xx розцінюється так само, як 5xx, для цілей повторної спроби — обидва варіанти ініціюють повтор. Повертайте 200, навіть якщо подія не стосується вашої інтеграції (наприклад, подія link.created, яка вам не потрібна), щоб уникнути зайвих повторних спроб.
Як працює ідемпотентність для подій вебхуків?
Кожне корисне навантаження вебхука містить поле event_id (UUID). Використовуйте його як ключ ідемпотентності у своєму приймачі: якщо ви отримуєте один і той самий event_id двічі (через повторну спробу після часткового збою), обробіть його лише один раз. Зберігайте отримані ID подій у таблиці дедуплікації з TTL не менше 72 годин (вікно повторних спроб). Навантаження повторної спроби ідентичне оригінальному — той самий event_id, те саме тіло — тому простої перевірки 'чи бачив я вже цей event_id?' достатньо.
Чому моя кінцева точка призупиняється автоматично?
Кінцеві точки автоматично призупиняються після 30 послідовних помилок доставки (код не 2xx або таймаут). Це не дає Elido нескінченно атакувати несправну кінцеву точку. Усуньте основну проблему (зазвичай: URL кінцевої точки змінився, сервер не працює або 30-секундний таймаут перевищується через повільну обробку), а потім відновіть роботу кінцевої точки на панелі керування. Після відновлення Elido не перевідправляє автоматично події, які були пропущені під час паузи — відправте їх вручну з журналу доставки, якщо вам потрібно їх відновити.
Чи можу я отримувати події кліків у реальному часі для кожного окремого кліка?
Так — увімкніть режим raw-click для кінцевої точки. У режимі raw-click Elido доставляє події click.created індивідуально без вікна пакетування протягом 2 секунд після кліка. Майте на увазі, що активний робочий простір може генерувати тисячі подій за хвилину в режимі raw-click; переконайтеся, що ваш приймач витримає таку пропускну здатність. Для більшості аналітичних сценаріїв використання за замовчуванням достатньо 5-секундної пакетної агрегації (до 100 кліків у корисному навантаженні), що створює значно менше HTTP-запитів.
Яке обмеження розміру корисного навантаження для подій вебхуків?
Розмір індивідуального корисного навантаження події не перевищує 10 КБ. Пакетні навантаження кліків (режим за замовчуванням) можуть містити до 100 подій у пакеті, з загальним обмеженням розміру 100 КБ. Якщо пакет перевищує 100 КБ, він автоматично розбивається на кілька доставок. Великі поля метаданих у кліках (наприклад, довгі URL реферерів) обрізаються до 2 КБ на кожне поле. Якщо ваш приймач має суворе обмеження розміру корисного навантаження, налаштуйте режим raw-click (одна подія на доставку) замість пакетного режиму.
Чи можна протестувати вебхуки локально під час розробки?
Використовуйте такі інструменти, як ngrok, Cloudflare Tunnel або localtunnel, щоб відкрити свій локальний сервер за допомогою публічної HTTPS-адреси, а потім зареєструйте цю адресу як кінцеву точку вебхука у своєму тестовому робочому просторі. Крім того, скористайтеся кнопкою тестового запуску вебхука на панелі керування, щоб надіслати зразок корисного навантаження для будь-якого типу події на зареєстровану кінцеву точку, не створюючи реальну подію. Elido CLI (elido webhook test --event click.created --endpoint https://...) також підходить для автоматизованого локального тестування.
Що відбувається з подіями вебхуків під час запланованого технічного обслуговування?
Події, згенеровані під час технічного обслуговування, ставляться в чергу в Redpanda і доставляються після завершення робіт. Сторінка статусу Elido (status.elido.app) заздалегідь повідомляє про заплановане технічне обслуговування. SLA доставки вебхуків не поширюється на анонсовані вікна технічного обслуговування. Для типового 30–60 хвилинного вікна обслуговування 72-годинне вікно повторних спроб означає, що жодна подія не буде остаточно втрачена — вони будуть доставлені в порядку їх створення, щойно кінцева точка знову стане доступною.
Keep reading
Синхронне доповнення API до асинхронних вебхуків — створюйте та запитуйте посилання програмно.
Отримуйте події конверсій через вебхуки від Stripe та Shopify — вхідна сторона вебхуків.
Режим SIEM доставляє події аудиту робочого простору — входи через SSO, ініціалізація SCIM, зміни ролей.
Події кліків у ClickHouse — альтернатива отриманню кліків через вебхуки на стороні запитів.
Готові спробувати?
Почніть з безкоштовного плану, оновіть, коли вам знадобиться власний домен.