Webhooks: підписка на події посилань та кліків

Webhooks передають події від Elido на ваш сервер у міру їх виникнення. Використовуйте їх замість опитування API, якщо вам потрібні дані в реальному часі — типові випадки використання включають синхронізацію метаданих посилань з вашою CRM, створення персональної панелі керування або запуск CI-конвеєра після публікації посилання.

Додавання ендпоінта для вебхука#

Панель керування → Вебхуки → Новий ендпоінт.
Вставте URL, на який ми маємо надсилати POST-запити. Він має бути HTTPS — ми відхиляємо звичайний HTTP під час створення.
Оберіть типи подій, які вам потрібні. Повний список наведено нижче.
(Опціонально) Вставте секрет підпису або дозвольте нам згенерувати його. Секрет відображається лише один раз; скопіюйте його перед тим, як залишити сторінку.
Зберегти. Ми негайно надішлемо тестову подію, щоб ви могли підтвердити доступність ендпоінта.

Каталог подій#

Поточні типи подій. Назви відповідають формату <resource>.<action> і залишаються стабільними в усіх версіях.

link.created — створено нове коротке посилання.
link.updated — змінено призначення, slug, термін дії або пароль.
link.deleted — посилання було м'яко видалено (доступне для відновлення протягом 30 днів).
link.clicked.aggregated — кожні 60 секунд ми надсилаємо кількість кліків для кожного посилання за попередній період. Ми не передаємо події для кожного окремого кліку через вебхуки (такий обсяг міг би перевантажити більшість ендпоінтів) — використовуйте експорт кліків для отримання необроблених даних.
domain.verified — перевірка DNS для власного домену пройдена.
domain.tls_renewed — Caddy оновив TLS-сертифікат для власного домену.
qr.generated — згенеровано QR-код у форматі SVG/PNG.
abuse.flagged — наш сканер URL позначив призначення як підозріле.
member.invited / member.removed — зміни у членстві робочого простору.

Структура корисного навантаження#

Кожна подія має однакову структуру:

{
  "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 є унікальним для кожної доставки. Використовуйте його для ідемпотентності — якщо ви отримаєте один і той самий id двічі (через повторну спробу), пропустіть дублікат.

Перевірка підписів#

Ми підписуємо кожне тіло вебхука за допомогою HMAC-SHA256, використовуючи секрет вашого ендпоінта. Підпис міститься в заголовку Elido-Signature у форматі t=<unix_ts>,v1=<hex>.

Для перевірки в 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;
}

Ми включаємо часову мітку в підписане корисне навантаження, щоб запобігти повторним атакам. Відхиляйте події, де |now - t| > 300 секунд.

Повторні спроби#

Ми повторюємо невдалі доставки (будь-яка відповідь, окрім 2xx, або відсутність відповіді протягом 10 секунд) з експоненціальною затримкою: 30с, 1хв, 5хв, 30хв, 2год, 12год. Після 6 невдач ми позначаємо ендпоінт як failing і припиняємо повторні спроби для цієї конкретної події. Ендпоінт залишається підписаним; нові події продовжуватимуть намагатися доставитися.

Якщо ендпоінт залишається в стані failing протягом 5 послідовних доставок — ми автоматично вимикаємо його та надсилаємо електронний лист власнику робочого простору. Знову увімкніть його в панелі керування після того, як виправите свій сервер.

Журнал доставок#

Відкрийте будь-який вебхук у панелі керування, щоб переглянути останні 500 доставок зі статус-кодом, часом відповіді та тілом запиту/відповіді для кожної. Невдалі доставки можна повторити вручну з цього вікна.

Локальне тестування#

Використовуйте Elido CLI для пересилання вебхуків на localhost:

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

CLI реєструє тимчасовий ендпоінт, який діє до натискання Ctrl-C, тунелює доставки на вашу машину та виводить тіло запиту для кожної події.

Ліміти#

20 ендпоінтів на робочий простір (Pro), 100 (Business).
Максимальний розмір підписаного корисного навантаження — 10 KB. Більші навантаження розділяються — data містить прапорець truncated: true та URL для отримання повного тіла.
50 подій на секунду стабільно для кожного ендпоінта. Сплески ставляться в чергу.

Усунення несправностей#

Ендпоінт повідомляє про 401 у журналі доставок. Ваш ендпоінт перевіряє підписи з неправильним секретом. Порівняйте секрет у Вебхуки → Ендпоінт → Налаштування з тим, що зберігається на вашому сервері.

Деякі події приходять двічі. Або ми повторили спробу після повільної відповіді, або ваш ендпоінт перевищив час очікування без відповіді. Використовуйте id події для ідемпотентності.

Показники link.clicked.aggregated не збігаються з панеллю аналітики. Панель керування відображає дані в реальному часі (з затримкою до 30с); вебхук агрегує дані за вікно в 60с. Також існує невелика розбіжність (~1%), оскільки боти, відфільтровані на панелі аналітики, все ще включаються в необроблені агрегати, доки вікно фільтрації ботів не закриється.