10 мин чтенияВозможности

Вебхуки для событий ссылок: payload, подписи, повторы

Вебхуки сокращателя для событий ссылок и кликов: конверт payload, click.created, проверка X-Elido-Signature на Node и Python, повторы.

Marius Voß
DevRel · edge infra

Вебхуки сокращателя ссылок Elido отправляют POST с подписанным JSON-конвертом на ваш HTTPS-эндпоинт всякий раз, когда в рабочем пространстве что-то меняется: ссылка создаётся, редактируется, удаляется, истекает или достигает лимита кликов, приглашается участник, подтверждается домен. Каждый запрос несёт заголовок X-Elido-Signature: v1=<hex>, то есть HMAC-SHA256 от {timestamp}.{raw_body}, а неудавшаяся доставка получает три попытки примерно за двадцать минут.

У кликов есть собственное событие, click.created, со своими правилами: payload с урезанными персональными данными, лимит скорости на эндпоинт и явное согласие для трафика ботов. Рассказывает о нём последний раздел. Эта статья посвящена исходящей половине поверхности API; входящую половину раскрывает быстрый старт по API и SDK сокращателя ссылок, а умные ссылки: разбор - опорная статья раздела функций, из которой происходят события ссылок.

Какие события ссылок сегодня вызывают вебхук

Каждое из событий ниже доходит до эндпоинта вебхука, подписавшегося на него по имени. Форма нового эндпоинта в дашборде предлагает флажки для восьми самых частых; API принимает любое имя из списка.

СобытиеСрабатывает, когдаФлажок в дашборде
link.createdСсылка создаётся по одной или массовым импортомда
link.updatedМеняются адрес назначения, настройки или статус, массовые правки, восстановленияда
link.deletedСсылка удаляется по одной или массовода
link.expiredСсылка проходит дату истечениятолько API
link.cap_reachedСсылка достигает максимального числа кликовтолько API
link.brokenПроверка битых ссылок видит, что адрес назначения не отвечаеттолько API
click.createdКлик засчитан (боты и сканеры пропускаются, если не включены)да, но не отмечен заранее
workspace.created, workspace.updatedРабочее пространство создаётся или меняются его настройкида
member.invited, member.removedУчастник добавляется (напрямую, через SCIM или принятым приглашением) или удаляетсяда
member.role_changedМеняется роль участникатолько API
invitation.created, invitation.acceptedПриглашение отправляется или принимаетсятолько API
domain.verified, domain.ssl_failedСвой домен проходит DNS-проверки или всё ещё не проходит их через 24 часатолько API
audit.eventЛюбая запись журнала аудитада

Зашифрованные ссылки добавляют ещё два: link.encrypted_created и link.encryption_rotated. Если не хотите вручную поддерживать список актуальным, создайте эндпоинт siem: он получает все события рабочего пространства, включая записи аудита, вообще без фильтра подписки. Единственное исключение - click.created: он приходит только на эндпоинты event, где отмечен.

События биллинга проходят через ту же очередь. Сервис биллинга публикует subscription.created, subscription.activated, subscription.paused, subscription.resumed, subscription.frozen, subscription.unfrozen, subscription.change_scheduled, subscription.change_canceled, usage.threshold_80, usage.threshold_100 и usage.overage_charged. Эндпоинт siem получает и их.

В планах, но пока не работает: фильтры по эндпоинтам вроде "только ссылки в папке X". До тех пор фильтруйте по data.slug или data.link_id в своём обработчике.

Страница эндпоинта вебхука в Elido с журналом доставок, показывающим доставленные события, повторную доставку и неудачную со статус-кодом 503

Создание эндпоинта вебхука через API

Эндпоинт принадлежит одному рабочему пространству. Создаётся POST-запросом на /v1/workspaces/{workspace_id}/webhooks:

curl -X POST "https://api.elido.app/v1/workspaces/$WORKSPACE_ID/webhooks" \
  -H "Authorization: Bearer elido_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/elido",
    "events": ["link.created", "link.updated", "link.deleted"],
    "description": "CRM sync",
    "kind": "event"
  }'

Ответ 201 содержит эндпоинт и, для видов event и siem, одноразовый секрет:

{
  "endpoint": {
    "id": 7,
    "workspace_id": 42,
    "url": "https://hooks.example.com/elido",
    "events": ["link.created", "link.updated", "link.deleted"],
    "is_active": true,
    "description": "CRM sync",
    "kind": "event",
    "config": {},
    "created_at": "2026-09-21T09:12:44Z"
  },
  "secret": "whsec_9f2c..."
}

Секрет генерирует Elido, вы его не отправляете. Скопируйте его сейчас: ни один последующий вызов его не вернёт. Поле kind принимает шесть значений. event и siem - подписанные JSON-доставки, о которых эта статья. discord, telegram, slack и sentry преобразуют те же события в сообщение чата или событие Sentry, аутентифицируются через URL или зашифрованный токен бота и не несут заголовков HMAC.

Тариф важен при создании. Для эндпоинта event нужен Pro, Business или Enterprise, а рабочее пространство на Free получает 402 Payment Required (в панели вместо этого открывается диалог перехода на другой тариф). Для эндпоинта siem нужен Business или Enterprise. У каналов чата и Sentry ограничений по тарифу нет. Уже существующие эндпоинты продолжают доставлять события, если рабочее пространство позже перейдёт на более низкий тариф.

Права: чтение эндпоинтов и журнала доставок требует workspace.view. Создание, редактирование, удаление, ротация секрета или повторная отправка доставки требуют workspace.edit, то есть администратора или владельца. Ключ API работает внутри рабочего пространства, для которого выпущен, и никогда выше роли, выбранной при его создании, так что ключ уровня viewer получит 403 на POST выше. Полный справочник: документация по вебхукам.

Конверт payload вебхука

Каждая подписанная доставка имеет один и тот же конверт из четырёх полей. В data лежит изменившаяся запись, поэтому для событий ссылок это строка ссылки:

{
  "type": "link.created",
  "workspace_id": 42,
  "data": {
    "id": 91834,
    "workspace_id": 42,
    "domain_id": 3,
    "slug": "spring-sale",
    "destination_url": "https://shop.example.com/spring",
    "title": "Spring sale landing",
    "tags": ["newsletter"],
    "status": "active",
    "expires_at": null,
    "max_clicks": null,
    "redirect_status": 302,
    "created_by_user_id": 17,
    "created_at": "2026-09-21T09:14:02.184311Z"
  },
  "timestamp": "2026-09-21T09:14:02Z"
}

Этот пример сокращён; настоящий data несёт все столбцы ссылки, включая правила таргетинга, папку, кампанию и поля сканирования. В теле нет ни ID события, ни short_url, поэтому при необходимости собирайте короткий URL из своего домена и slug. Запланированные события отправляют объект поменьше: у link.expired это link_id, slug и destination_url, а link.cap_reached добавляет cap и clicks.

Об одном исправлении стоит знать, если вы логировали payload до исправления редактирования: секретные поля теперь удаляются до того, как payload покидает Elido: раньше password_hash защищённой паролем ссылки и token приглашения появлялись в data; теперь их нет ни в новых доставках, ни в журнале доставок. Если вы сохраняли старые payload, эти данные стоит удалить.

Проверка заголовка X-Elido-Signature

Каждый подписанный запрос несёт такие заголовки:

X-Elido-Signature: v1=5d8f0c3e...
X-Webhook-Signature: v1=5d8f0c3e...
X-Webhook-Timestamp: 1790068442
X-Webhook-Event: link.created
X-Webhook-Delivery: 55120
User-Agent: Elido-Webhooks/1.0

Два заголовка подписи содержат одно и то же значение, а X-Webhook-Signature - совместимый псевдоним. Elido вычисляет HMAC-SHA256, как определено в RFC 2104, с ключом, равным всей строке whsec_..., от метки времени, точки и байтов сырого тела. К hex-дайджесту добавляется префикс v1=. Поля t= внутри заголовка нет; метка времени лежит в собственном заголовке.

Схема проверки подписи: заголовки X-Elido-Signature и X-Webhook-Timestamp, сырое тело и секрет формируют HMAC-SHA256 от ts, точки и body, который сравнивается за постоянное время как hex с префиксом v1=.

В Node подписывайте сырые байты, а не повторно сериализованный объект. Поэтому для этого маршрута в Express нужен express.raw({ type: "application/json" }):

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

export function verifyElido(secret, headers, rawBody, toleranceSec = 300) {
  const ts = headers["x-webhook-timestamp"] ?? "";
  if (!/^\d+$/.test(ts)) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false;

  const mac = createHmac("sha256", secret).update(`${ts}.`).update(rawBody);
  const expected = Buffer.from("v1=" + mac.digest("hex"));

  // During a rotation the old secret signs X-Elido-Signature-Previous.
  return ["x-elido-signature", "x-elido-signature-previous"].some((name) => {
    const got = Buffer.from(headers[name] ?? "");
    return got.length === expected.length && timingSafeEqual(got, expected);
  });
}

Проверка длины важна: timingSafeEqual в Node выбрасывает исключение на буферах разного размера, а не возвращает false. Версия на Python со стандартным модулем hmac:

import hashlib
import hmac
import time


def verify_elido(secret: str, headers, raw_body: bytes, tolerance: int = 300) -> bool:
    ts = headers.get("X-Webhook-Timestamp", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > tolerance:
        return False
    digest = hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256)
    expected = "v1=" + digest.hexdigest()
    for name in ("X-Elido-Signature", "X-Elido-Signature-Previous"):
        got = headers.get(name)
        if got and hmac.compare_digest(got, expected):
            return True
    return False

Если проверка продолжает не проходить, в руководстве по проверке подписей вебхуков есть версия на Go, узел Code для n8n и типичные причины несовпадения. Пятиминутное окно - ваша проверка, а не наша. Elido ставит свежую метку времени на каждую попытку, включая повторные, поэтому законный повтор никогда не выглядит устаревшим. Без окна любой, кто перехватил один запрос, мог бы воспроизвести его на следующей неделе, и подпись всё равно совпала бы.

Ротация выполняется через POST /v1/workspaces/{workspace_id}/webhooks/{id}/rotate-secret или кнопкой Rotate на странице эндпоинта. Новый секрет показывается один раз. В следующие семь дней каждая доставка несёт также X-Elido-Signature-Previous, подписанный старым секретом, поэтому обе функции выше проверяют и его. Разверните новый секрет в любой момент этой недели, и ничего не сломается.

Политика повторов вебхуков

Воркер доставки подбирает ожидающие доставки каждые несколько секунд, поэтому изменение ссылки обычно доходит до вас за секунды. Любой ответ 2xx помечает доставку выполненной. Статус не 2xx, сетевая ошибка или отсутствие ответа в течение 10 секунд считаются неудачной попыткой.

Столбчатая диаграмма расписания повторов вебхука: попытка 1 в T+0, попытка 2 через пять минут после неудачи в T+5m, попытка 3 ещё через пятнадцать минут в T+20m, затем доставка помечается как неудавшаяся и автоматических попыток больше нет, пока кто-то не нажмёт Retry или не вызовет эндпоинт повтора

Три попытки на доставку, двадцать минут от начала до конца. Это сделано коротким намеренно, и, честно говоря, короче, чем я выбрал бы для получателя за нестабильным VPN. Двухчасовой простой на вашей стороне автоматические повторы не покроют. Покрывает его журнал доставок: GET /v1/workspaces/{workspace_id}/webhooks/{id}/deliveries перечисляет каждую доставку со статусом, HTTP-кодом, задержкой, числом попыток и временем следующего повтора, а страница эндпоинта показывает те же строки с кнопкой Retry. Retry, или POST .../deliveries/{delivery_id}/retry, заново взводит неудавшуюся или доставленную доставку со свежим бюджетом из трёх попыток и возвращает 202. Для доставки в статусе pending возвращается 409.

Некоторые сбои обходят повторы. Эндпоинт Telegram без chat_id или некорректный DSN Sentry помечаются неудавшимися сразу, потому что повтор запроса не исправит конфигурацию. Чтобы отключить эндпоинт, не удаляя его, отправьте PUT с "is_active": false; приостановленные эндпоинты не получают новых доставок.

Если ваш обработчик делает тяжёлую работу, сначала верните 200 и поставьте задачу в очередь. Именно на десятисекундной отсечке медленный, но успешный обработчик превращается в дубликат, и это подводит нас к дедупликации.

Планируете получателя для своей команды? Сторона дашборда показана на странице функции вебхуков.

Идемпотентность и порядок вебхуков

Elido доставляет как минимум один раз. Раздел о повторах показал один из способов появления дубликата: ваш обработчик фиксирует работу, затем не укладывается в десятисекундное окно, и Elido отправляет доставку снова. Ручной Retry пересылает намеренно.

В обоих случаях значение X-Webhook-Delivery остаётся прежним, потому что это ID одной доставки на один эндпоинт, а не одной попытки. Ключуйтесь по нему:

CREATE TABLE elido_webhook_seen (
  delivery_id BIGINT PRIMARY KEY,
  received_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- in the handler, inside the same transaction as your work:
INSERT INTO elido_webhook_seen (delivery_id) VALUES ($1)
ON CONFLICT (delivery_id) DO NOTHING
RETURNING delivery_id;
-- no row back means you've already handled this delivery

Два эндпоинта, подписанные на одно событие, получают разные ID доставки, поэтому дедуплицируйте по каждому эндпоинту. При редких перезапусках на нашей стороне событие может попасть в очередь дважды как отдельные доставки; если двойная запись навредит, добавьте вторую защиту по type плюс data.id плюс data.updated_at.

Обещания порядка нет. Доставки уходят начиная с самой старой по сроку, но повтор раннего события может прийти после более позднего. Перед перезаписью ссылки сравнивайте data.updated_at с сохранённым значением и не опирайтесь на timestamp конверта для упорядочивания: у него точность только одна секунда.

Вебхук click.created

click.created отправляет одну подписанную доставку на каждый засчитанный клик. Он не стоит на пути редиректа: редирект публикует клик и идёт дальше, как объясняет статья о fire-and-forget приёме кликов, а событие собирается позже по сохранённому клику. Между кликом и POST ждите несколько секунд, а не миллисекунды.

Объект data выглядит так:

{
  "type": "click.created",
  "workspace_id": 42,
  "timestamp": "2026-11-12T10:04:31Z",
  "data": {
    "id": "clk_3_99120",
    "link_id": 9183,
    "workspace_id": 42,
    "slug": "spring",
    "host": "go.acme.example",
    "short_url": "https://go.acme.example/spring",
    "timestamp": "2026-11-12T10:04:29Z",
    "country": "DE",
    "device": "mobile",
    "browser": "Safari",
    "referer_host": "news.ycombinator.com",
    "ip": "203.0.113.0",
    "is_bot": false,
    "is_scanner": false
  }
}

Несколько правил определяют, что приходит:

  • Сначала приватность. Payload строится после применения настроек приватности аналитики рабочего пространства. IP всегда только усечённая сеть (/24 для IPv4, /48 для IPv6), а в режиме без персональных данных его нет вовсе. Реферер урезается до хоста; пути и строки запроса никогда не уходят.
  • Боты по умолчанию выключены. Клики с флагами is_bot или is_scanner (почтовый сканер безопасности, предзагружающий ссылку) пропускаются, пока вы не отметите «Include bot and scanner clicks» на эндпоинте или не передадите config.include_bot_clicks: true через API. Известные краулеры и боты предпросмотра ссылок никогда не считаются кликами, поэтому не отправляются.
  • Лимит скорости, а не очередь. Каждый эндпоинт получает не больше 50 событий кликов в секунду. Остальное отбрасывается, а не откладывается, так что вирусная ссылка не завалит ваш приёмник, но и вебхук на пике не является полным журналом. Если важен каждый клик, сверяйтесь с API аналитики.
  • Дедупликация по data.id. Доставка идёт по принципу «как минимум один раз», как и у остальных событий. data.id не меняется, если клик обработан дважды, а X-Webhook-Delivery покрывает повторы одной доставки.
  • Те же повторы и подпись. Три попытки (сразу, через 5 минут, через 15 минут) и проверка X-Elido-Signature из начала этой статьи.

Событие получают только эндпоинты типа event, у которых отмечен click.created. Форма в дашборде показывает его, но никогда не отмечает заранее, а эндпоинты Discord, Telegram, Sentry и siem его не получают. Zapier (Catch Hook в Webhooks by Zapier), Make (Custom webhook) и n8n (узел Webhook) могут принимать его как триггер.

Для данных о кликах всё ещё имеют смысл два других пути. Пересылка событий превращает каждый клик в серверное событие в уже используемом вами инструменте: события кликов по ссылкам в Mixpanel, события кликов в профилях Klaviyo или метрики редиректов в Datadog для операционных дашбордов. А API аналитики, GET /v1/analytics/workspaces/{workspace_id}/clicks/recent плюс выгрузка clicks.csv, - это полный журнал. Что из этого подойдёт, разбирает статья вебхуки или опрос для отслеживания кликов.

Прочитайте опорную статью: умные ссылки: разбор.

Читайте также в блоге

Частые вопросы

Отправляет ли Elido вебхук на каждый клик по ссылке?

Да, через событие click.created: одна подписанная доставка на каждый засчитанный клик, через несколько секунд после него. Клики ботов и сканеров безопасности пропускаются, пока эндпоинт не включит их, а каждый эндпоинт ограничен 50 событиями кликов в секунду: остальное отбрасывается, а не ставится в очередь. Для полного журнала вирусной ссылки читайте ещё и API аналитики.

Как проверить подпись вебхука Elido?

Вычислите HMAC-SHA256 от значения X-Webhook-Timestamp, точки и сырого тела запроса с ключом, равным вашему секрету whsec_. Закодируйте результат в hex, добавьте префикс v1= и сравните за постоянное время с заголовком X-Elido-Signature. Отклоняйте метки времени старше пяти минут.

Сколько раз Elido повторяет неудавшийся вебхук?

Для каждой доставки выделено три попытки: первая сразу, вторая через пять минут после неудачи и третья через пятнадцать минут после этого. Неудачей считается любой статус не 2xx, сетевая ошибка или ответ медленнее десяти секунд. После третьей попытки доставка помечается как неудавшаяся, пока вы не нажмёте Retry.

Чем отличается X-Elido-Signature от X-Webhook-Signature?

Только названием. Оба заголовка несут одну и ту же подпись v1=. X-Elido-Signature - основной, а X-Webhook-Signature оставлен как совместимый псевдоним, поэтому в новом коде используйте первый. Во время ротации секрета Elido семь дней также отправляет X-Elido-Signature-Previous, подписанный старым секретом.

Как не обработать один и тот же вебхук дважды?

Сохраняйте значение заголовка X-Webhook-Delivery и пропускайте любой запрос, значение которого вы уже обработали. Оно идентифицирует одну доставку на один эндпоинт и остаётся прежним при автоматических повторах и ручной повторной отправке, так что достаточно уникального индекса по нему.

Кто может создавать и удалять вебхуки в рабочем пространстве?

Администраторы и владельцы рабочего пространства. Для списка эндпоинтов и чтения журнала доставок нужен доступ на просмотр; для создания, редактирования, удаления, ротации секрета или повторной отправки доставки нужно разрешение workspace.edit. Ключи API ограничены ролью, выбранной при создании ключа.

Попробуйте Elido

Вставьте URL - получите короткую ссылку

Без регистрации. Ссылка живёт 30 дней. Зарегистрируйтесь, чтобы оставить её навсегда.

Нужен бесплатный аккаунт. Бесплатный план включает всего 25 ссылок. Уже есть аккаунт? Войти

Попробуйте Elido

URL-сокращатель с хостингом в ЕС: собственные домены, глубокая аналитика, открытый API. Бесплатный тариф - без банковской карты.

Теги
url shortener webhooks
link click webhook
webhook signature verification
webhook retry policy
webhook idempotency
webhook payload

Читать дальше