Вебхуки: подпишись на события ссылок и кликов

Вебхуки доставляют события из Elido на твой сервер по мере их возникновения. Используй их вместо опроса API, когда нужны данные в реальном времени — типичные сценарии: синхронизация метаданных ссылок в CRM, построение кастомного дашборда или запуск CI-пайплайна при публикации ссылки.

Добавить эндпоинт#

Dashboard → Webhooks → New endpoint.
Вставь URL, на который мы должны отправлять POST. Должен быть HTTPS — plain HTTP отклоняется при создании.
Выбери нужные типы событий. Полный список ниже.
(Опционально) Вставь signing secret или позволь нам его сгенерировать. Secret показывается один раз; скопируй его до выхода со страницы.
Save. Мы немедленно отправляем тестовое событие, чтобы ты мог убедиться, что эндпоинт доступен.

Каталог событий#

Текущие типы событий. Имена следуют формату <resource>.<action> и остаются стабильными между версиями.

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

Структура payload#

Каждое событие имеет одинаковую оболочку:

{
  "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, используя secret эндпоинта. Подпись находится в заголовке 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;
}

Мы включаем timestamp в подписанный payload для защиты от replay-атак. Отклоняй события, где |now - t| > 300 секунд.

Повторные попытки#

Мы повторяем неудачные доставки (любой ответ не 2xx или отсутствие ответа в течение 10 секунд) с экспоненциальным backoff: 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).
Максимальный размер подписанного payload — 10 КБ. Более крупные payloads разбиваются — data включает флаг truncated: true и URL для получения полного тела.
50 событий в секунду без превышения на эндпоинт. Всплески ставятся в очередь.

Устранение неполадок#

Эндпоинт сообщает 401 в логе доставки. Твой эндпоинт проверяет подписи с неправильным secret. Сравни secret в Webhooks → Endpoint → Settings с тем, что хранит твой сервер.

Некоторые события приходят дважды. Либо мы повторили попытку после медленного ответа, либо твой эндпоинт истёк без ответа. Используй id события для идемпотентности.

Счётчики link.clicked.aggregated не совпадают с аналитическим дашбордом. Дашборд работает в реальном времени (в течение 30с после клика); вебхук с окном в 60с. Также есть небольшое расхождение (~1%), потому что боты, отфильтрованные на дашборде, всё ещё включены в сырые агрегаты до закрытия окна бот-фильтра.