Вебхуки: підписка на події посилань і робочої області

Вебхуки надсилають події з Elido на ваш сервер у момент їх виникнення, тож вам не потрібно опитувати API. Типові випадки використання: синхронізація метаданих посилань із CRM, підтримання внутрішнього індексу посилань в актуальному стані або запуск завдання, коли посилання опубліковано.

Вебхуки охоплюють зміни посилань, доменів, учасників і робочої області. Вони не містять даних про окремі кліки. Для даних про кліки використовуйте експорт кліків або інтеграцію подій, як-от Mixpanel. Вебхук-події для кожного окремого кліку заплановано на майбутнє.

Додавання кінцевої точки вебхука

1. Перейдіть до Dashboard → Webhooks.
2. Введіть URL-адресу, на яку ми маємо надсилати POST-запити, і необов'язковий опис.
3. Виберіть тип кінцевої точки: Events (ви обираєте типи подій) або SIEM (firehose) (усі події в робочій області).
4. Для кінцевої точки Events позначте потрібні типи подій. Події link.* позначені за замовчуванням.
5. Натисніть Add endpoint. Секрет підпису з'явиться один раз, безпосередньо під формою. Скопіюйте його зараз: Elido більше його не покаже.

URL-адреса має бути HTTPS. Звичайний http:// відхиляється під час збереження кінцевої точки, за винятком localhost і 127.0.0.1, які залишаються дозволеними для локальної розробки.

Ви можете призупинити та відновити кінцеву точку зі списку. Призупинена кінцева точка не отримує нових доставок, а все, що досі стоїть у її черзі, чекатиме, доки ви її не відновите.

Хто може керувати вебхуками

Будь-хто в робочій області може переглядати кінцеві точки та журнал доставок. Для створення, редагування, призупинення, видалення, ротації секрету й повторної спроби доставки потрібен дозвіл workspace.edit, який мають вбудовані ролі Admin і Owner. Ключ API може викликати ті самі кінцеві точки вебхуків API, якщо його роль має цей дозвіл.

Типи кінцевих точок

• Events (event): отримує лише типи подій, на які ви підписалися. Підписані.
• SIEM (siem): отримує кожну опубліковану для робочої області подію, зокрема audit.event для кожного запису журналу аудиту. Підписані. Призначені для конвеєрів журналів і засобів безпеки.
• Discord, Telegram і Sentry: канали чату та сповіщень, які повторно використовують ту саму систему доставки, але надсилають власний формат повідомлень постачальника. Вони автентифікуються через URL-адресу або токен постачальника, тому не містять заголовків підпису. Див. Discord, Telegram і Sentry.

Усе нижче про підписи та секрети стосується лише кінцевих точок Events і SIEM.

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

Назви відповідають формату <resource>.<action>. Форма панелі керування пропонує найпоширеніші з них; через API можна підписати кінцеву точку Events на будь-який тип із цього списку, а кінцева точка SIEM отримує їх усі.

У засобі вибору на панелі керування:

• link.created: створено коротке посилання, зокрема посилання, створені масово.
• link.updated: посилання змінено (призначення, заголовок, теги, термін дії тощо), відновлено, змінено його статус або модерація змінила його статус безпеки.
• link.deleted: коротке посилання програмно видалено.
• workspace.updated: змінено налаштування робочої області.
• workspace.created: публікується під час створення робочої області. Оскільки кінцева точка не може існувати в робочій області до її створення, зазвичай ви не отримуватимете цю подію.
• member.invited: хтось приєднався до робочої області через пряме додавання, прийняте запрошення або підготовку SCIM.
• member.removed: учасника видалено вручну або через SCIM.
• audit.event: одна подія для кожного запису журналу аудиту.

Доступні через API або кінцеву точку SIEM:

• link.expired: термін дії посилання минув.
• link.cap_reached: посилання досягло ліміту кліків. data містить cap і clicks.
• link.broken: перевірка стану посилання Elido виявила, що призначення не працює. data містить status_code, error_message і first_seen_at.
• link.encrypted_created і link.encryption_rotated: для зашифрованих посилань.
• domain.verified: користувацький домен пройшов перевірку DNS.
• domain.ssl_failed: записи DNS користувацького домену все ще не знайдено через 24 години після його додавання. Попри назву, йдеться про перевірку DNS, а не оновлення сертифіката.
• member.role_changed: роль учасника змінено. data містить old_role, new_role і changed_by_user_id.
• invitation.created і invitation.accepted.
• Події виставлення рахунків: subscription.* (наприклад, subscription.activated, subscription.renewed, subscription.canceled) і usage.threshold_80, usage.threshold_100.

Заплановано, але наразі не надсилаються: link.clicked.aggregated (кількість кліків за посиланням за кожен період), події для кожного окремого кліку, conversion.recorded, domain.tls_renewed, qr.generated та окрема подія abuse.flagged. Рішення модерації щодо посилання наразі надходить як link.updated з новим abuse_status.

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

Кожна підписана доставка є запитом POST із Content-Type: application/json, User-Agent: Elido-Webhooks/1.0 і такою оболонкою:

{
  "type": "link.created",
  "workspace_id": 4123,
  "timestamp": "2026-09-22T09:42:11Z",
  "data": {
    "id": 891234,
    "workspace_id": 4123,
    "domain_id": 12,
    "slug": "spring-2026",
    "destination_url": "https://acme.com/spring-sale",
    "title": "Spring sale",
    "tags": ["email"],
    "status": "active",
    "expires_at": null,
    "created_by_user_id": 5821,
    "created_at": "2026-09-22T09:42:11Z"
  }
}

• type - це тип події. Він також міститься в заголовку X-Webhook-Event.
• timestamp - час виникнення події у форматі UTC.
• data залежить від події. Для подій link.* це повний об'єкт посилання (приклад вище скорочено). Для інших подій це невеликий об'єкт з ідентифікаторами та полями, переліченими в каталозі.
• Секрети ніколи не залишають Elido: такі поля, як хеш пароля посилання або токен запрошення, видаляються з data перед доставкою.

У тілі поки що немає поля id події; ідентифікатор для кожної події заплановано на майбутнє. Для ідемпотентності використовуйте заголовок X-Webhook-Delivery, описаний нижче.

Заголовки та підписи

Кожна доставка на кінцеву точку Events або SIEM містить:

Заголовок	Значення
X-Elido-Signature	v1=, після якого вказано hex-підпис HMAC-SHA256
X-Webhook-Signature	Те саме значення, що й у X-Elido-Signature, для старих інтеграцій
X-Webhook-Timestamp	Час у секундах Unix, коли цей запит було підписано
X-Webhook-Event	Тип події, наприклад link.created
X-Webhook-Delivery	Ідентифікатор доставки. Він не змінюється під час повторних спроб
X-Elido-Signature-Previous	Лише під час ротації секрету: той самий підпис, створений старим ключем

Підпис обчислюється так:

v1=hex( HMAC-SHA256( secret, "{X-Webhook-Timestamp}.{raw request body}" ) )

Ключем є весь рядок вашого секрету, включно з префіксом whsec_, використаний без змін. Підписуйте отримані необроблені байти, а не повторно серіалізований об'єкт JSON, і порівнюйте за сталий час. Короткий приклад Node (Express):

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

const SECRET = process.env.ELIDO_WEBHOOK_SECRET; // full whsec_... value

function same(a, b = "") {
  const x = Buffer.from(a);
  const y = Buffer.from(b);
  return x.length === y.length && timingSafeEqual(x, y);
}

const app = express();
app.post(
  "/webhooks/elido",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ts = req.get("X-Webhook-Timestamp") ?? "";
    if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
      return res.status(400).send("stale timestamp");
    }
    const expected =
      "v1=" +
      createHmac("sha256", SECRET)
        .update(`${ts}.`)
        .update(req.body)
        .digest("hex");
    const ok = [
      req.get("X-Elido-Signature"),
      req.get("X-Elido-Signature-Previous"),
    ].some((sig) => same(expected, sig));
    if (!ok) return res.status(401).send("bad signature");

    const event = JSON.parse(req.body.toString("utf8"));
    // queue event for processing, then answer quickly
    res.sendStatus(200);
  },
);

Версії для Python і Go, тестовий вектор і поширені помилки див. у посібнику з перевірки підписів вебхуків.

Ротація секрету підпису

Відкрийте кінцеву точку в Dashboard → Webhooks і натисніть Rotate secret. Новий секрет whsec_ буде показано один раз, після чого Elido підписуватиме ним.

Старий ключ залишається дійсним протягом 7-денного пільгового періоду. У цей період кожна доставка містить два підписи: X-Elido-Signature з новим ключем і X-Elido-Signature-Previous зі старим, тож отримувач, який ще не перемкнувся, продовжує проходити перевірку. Приймайте будь-який із цих заголовків, поки розгортаєте новий секрет.

Кінцеві точки, створені до 22 вересня 2026 року, є одним винятком: під час їхньої першої ротації X-Elido-Signature-Previous не створюється, тому початковий секрет одразу припиняє працювати. Розгорніть новий секрет відразу після першої ротації. Кінцеві точки, створені відтоді, підписують обома ключами вже під час першої ротації. Починаючи з другої ротації діє 7-денне перекриття.

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

Доставка вважається невдалою у разі будь-якої відповіді не 2xx, мережевої помилки або відсутності відповіді протягом 10 секунд. Кожна доставка має загалом 3 спроби:

1. Перша спроба - через кілька секунд після події.
2. Повторна спроба - приблизно через 5 хвилин після першої невдачі.
3. Остання повторна спроба - приблизно через 15 хвилин після другої невдачі.

Якщо третя спроба не вдається, доставку позначено як failed, і автоматично повторювати її більше не будуть. Кінцева точка залишається активною, а нові події продовжують надходити. Ваша кінцева точка може побачити одну доставку більше одного разу (наприклад, коли вона обробила запит, але відповіла після 10-секундного тайм-ауту), тож усувайте дублікати за X-Webhook-Delivery.

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

Відкрийте кінцеву точку в Dashboard → Webhooks, щоб переглянути її 100 останніх доставок. Для кожної з них ви отримуєте тип події, статус (pending, delivered або failed), HTTP-статус, який повернув ваш сервер, час відповіді, використану кількість спроб із 3, час створення та завершення, час наступної повторної спроби для очікуваних доставок, останню помилку та повне надіслане корисне навантаження.

Для будь-якої доставленої або невдалої доставки є кнопка Retry. Вона знову ставить ту саму доставку в чергу (з тим самим ідентифікатором X-Webhook-Delivery, але зі свіжим підписом) із новим бюджетом у 3 спроби. Через API GET /v1/workspaces/{workspace_id}/webhooks/{id}/deliveries переглядає старіші доставки сторінками за допомогою limit (до 100) і offset, а POST .../deliveries/{delivery_id}/retry виконує ту саму дію, що й кнопка. Якщо ви не можете самостійно відтворити доставку, служба підтримки Elido може зробити це за вас.

Запис тіла відповіді вашого сервера в журналі заплановано на майбутнє.

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

Заплановано CLI-команду, яка пересилає вебхуки на localhost (npx @elido/cli webhooks forward). Поки її немає, відкрийте доступ до локального сервера через тунель, як-от ngrok або Cloudflare Tunnel, додайте HTTPS-URL тунелю як кінцеву точку та видаліть її після завершення роботи.

Обмеження

• 10 секунд на відповідь вашої кінцевої точки.
• 3 спроби доставки для кожної події, плюс ручні повторні спроби.
• API журналу доставок повертає не більше 100 доставок на сторінку.

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

Підпис ніколи не збігається. Зазвичай причини такі: ваш фреймворк розібрав і повторно серіалізував JSON до того, як ви обчислили хеш (хешуйте необроблене тіло), ви видалили префікс whsec_ із ключа або підписуєте тіло за timestamp, а не за заголовком X-Webhook-Timestamp. У дописі про перевірку підписів є тестовий вектор для перевірки вашого коду.

Після ротації підпис перестав збігатися. На сервері все ще зберігається старий секрет. Розгорніть новий. Якщо кінцеву точку створено до 22 вересня 2026 року, під час її першої ротації немає X-Elido-Signature-Previous, на який можна було б перейти.

Деякі події надходять двічі. Elido повторив доставку, оскільки ваша кінцева точка відповіла помилкою або працювала довше ніж 10 секунд. Усувайте дублікати за X-Webhook-Delivery і відповідайте кодом 2xx до виконання повільної роботи.

Певний тип події ніколи не надходить. Перевірте, чи кінцева точка підписана на нього, не призупинена та чи є цей тип у наведеному вище каталозі. Типи, позначені як заплановані, ще не надсилаються.