Skip to content

Вебхуки ​

Как выглядит доставка ​

Web3alert отправляет HTTP POST с телом в формате JSON.

json
{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "subscription.event",
  "timestamp": "2026-11-21T12:00:00.000Z",
  "subscription": { "id": "example-subscription-id" },
  "trigger": { "fullname": "example.project.transfer", "name": "Transfer" },
  "header": "Example project",
  "icon": "https://example.com/icon.png",
  "cover": "https://example.com/cover.png",
  "message": "Example alert",
  "links": [{ "text": "View event", "url": "https://example.com/event" }],
  "object": { "amount": "100" }
}
ПолеЗначение
idПрефикс evt_ и 32 шестнадцатеричных символа в нижнем регистре. Совпадает с webhook-id и сохраняется при каждой попытке.
typesubscription.event для события или subscription.test для тестовой доставки.
timestampВремя, когда Web3alert впервые подготовил доставку, в формате ISO 8601 UTC. Сохраняется при каждой попытке.
subscription.idID подписки.
trigger.fullname, trigger.nameПолное имя и имя триггера.
header, messageЗаголовок или имя проекта и длинный или короткий текст оповещения.
icon, cover, linksURL изображений и ссылки с полями text и url, если они заданы.
objectДанные события или пустой объект.
ЗаголовокЗначение
content-typeapplication/json.
webhook-idID доставки, совпадает с id в теле.
webhook-timestampВремя этой попытки в секундах Unix, переданное строкой с целым числом.
webhook-signatureДля эндпоинтов с секретом подписи v1,<signature> содержит HMAC-SHA256 в кодировке base64.

Проверка подписи ​

Проверяйте исходное тело запроса до разбора JSON. Вычислите HMAC от webhook-id.webhook-timestamp.raw-body с ключом, полученным декодированием части секрета после whsec_ из base64. Используйте время из заголовка и отклоняйте запросы, если оно отличается от времени на ваших часах более чем на пять минут в любую сторону. Для проверки также подходят библиотеки Standard Webhooks.

Примеры принимают исходное тело как Buffer в Node.js или bytes в Python, словарь со строковыми значениями заголовков и именами в нижнем регистре, а также секрет подписи эндпоинта. Принимайте запрос только после успешной проверки.

Node.js ​

js
import { createHmac, timingSafeEqual } from 'node:crypto'

function verifyWebhook(rawBody, headers, secret, now = Math.floor(Date.now() / 1000)) {
  const id = headers['webhook-id']
  const timestamp = headers['webhook-timestamp']
  const signatures = headers['webhook-signature']
  if (!id || !timestamp || !signatures || !secret.startsWith('whsec_')) return false
  // Точка в ID позволяет иначе разделить те же подписанные байты id.timestamp.body.
  if (!/^[A-Za-z0-9_-]{1,256}$/.test(id)) return false
  if (!/^[0-9]{1,16}$/.test(timestamp) || Math.abs(now - Number(timestamp)) > 300) return false

  const encodedKey = secret.slice(6)
  const key = Buffer.from(encodedKey, 'base64')
  if (key.length === 0 || key.toString('base64') !== encodedKey) return false

  const digest = createHmac('sha256', key).update(`${id}.${timestamp}.`).update(rawBody)
  const expected = Buffer.from(digest.digest('base64'))
  let valid = false
  for (const entry of signatures.trim().split(/\s+/)) {
    if (!entry.startsWith('v1,')) continue
    const candidate = Buffer.from(entry.slice(3))
    if (candidate.length === expected.length && timingSafeEqual(candidate, expected)) valid = true
  }
  return valid
}

Python ​

python
import base64
import hashlib
import hmac
import re
import time
from binascii import Error


def verify_webhook(raw_body, headers, secret, now=None):
    id_ = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not id_ or not timestamp or not signatures or not secret.startswith("whsec_"):
        return False
    # Точка в ID позволяет иначе разделить те же подписанные байты id.timestamp.body.
    if not re.fullmatch(r"^[A-Za-z0-9_-]{1,256}$", id_):
        return False
    if now is None:
        now = int(time.time())
    if not re.fullmatch(r"[0-9]{1,16}", timestamp) or abs(now - int(timestamp)) > 300:
        return False

    encoded_key = secret[6:]
    try:
        key = base64.b64decode(encoded_key, validate=True)
    except (Error, ValueError):
        return False
    if not key or base64.b64encode(key).decode("ascii") != encoded_key:
        return False

    signed = f"{id_}.{timestamp}.".encode("utf-8") + raw_body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest())
    valid = False
    for entry in signatures.split():
        if entry.startswith("v1,") and hmac.compare_digest(entry[3:].encode("utf-8"), expected):
            valid = True
    return valid

Контрольный вектор ​

Чтобы проверить любой пример на контрольном векторе Standard Webhooks, используйте тело из таблицы без перевода строки в конце. Для этих исторических данных передайте 1614265330 четвёртым аргументом (now). Проверка должна вернуть true в Node.js или True в Python.

Входные данныеЗначение
Секретwhsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw
webhook-idmsg_p5jXN8AQM9LWM0D4loKWxJek
webhook-timestamp1614265330
Исходное тело{"test": 2432232314}
Ожидаемый заголовок webhook-signaturev1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

Секрет подписи ​

При создании вебхука в приложении Web3alert показывает секрет один раз. MCP-инструмент add_webhook тоже возвращает его один раз в поле signingSecret. Сохраните секрет для принимающей стороны. Секрет Web3alert состоит из префикса whsec_ и 32 байт, закодированных стандартным base64 с дополнением.

Создайте или замените секрет в приложении либо через POST /api/resources/{fullname}/signing-secret. Новый секрет применяется к доставкам примерно в течение 10 секунд. До этого используется прежний секрет, если он был. Когда новый секрет вступит в силу, Web3alert перестанет подписывать доставки прежним. Эндпоинты, созданные до появления подписей, получают доставки без подписи, пока вы не создадите секрет.

При переносе проекта в другой воркспейс секреты подписи перенесённых вместе с ним вебхуков удаляются. Эти вебхуки отображаются без подписи. Чтобы снова подписывать доставки, пользователь с правами на управление новым воркспейсом должен создать новый секрет для каждого перенесённого вебхука.

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

Ответ 2xx означает, что получатель принял доставку. Отвечайте быстро, поскольку время запроса по умолчанию ограничено 4 секундами. Web3alert повторяет попытку при HTTP 429, любом ответе 5xx, превышении времени ожидания или сетевой ошибке до получения ответа, например разрыве соединения или сбое DNS либо TLS. Остальные результаты завершают доставку. Тестовые доставки выполняются без повторных попыток.

При ответе HTTP 3xx Web3alert считает доставку отклонённой и не повторяет попытку. Отклонение учитывается при блокировке подписки после пяти недоставленных событий подряд.

Укажите конечный HTTPS-адрес. Web3alert не следует перенаправлениям, в том числе при тестовых доставках.

Если в момент повторной попытки сервис отправки вебхуков Web3alert недоступен, Web3alert ждёт и повторяет попытку с тем же номером. Если сервис недоступен на первой попытке, Web3alert планирует попытку 2 с причиной webhook service unavailable и кодом channel.webhook.retry_scheduled. Если время ожидания ответа сервиса истекло, попытка засчитывается как ошибка, допускающая повтор, с причиной webhook service timed out и повторяется по расписанию.

После неудачной попыткиМинимальное время до следующей попытки
15 секунд
21 минута
310 минут
41 час
56 часов

Всего на доставку даётся не более шести попыток. При таких интервалах шесть попыток занимают около 7 часов и 11 минут плюс время доставки. При повторных попытках сохраняются тело и webhook-id. Каждая попытка использует действующий URL и новый webhook-timestamp, а Web3alert подписывает её действующим секретом, если он настроен. Доставка выполняется как минимум один раз, поэтому используйте webhook-id, чтобы не обрабатывать одно событие повторно. Повторные попытки не расходуют лимит частоты уведомлений подписки.

Если приостановить или удалить подписку, повторные попытки прекращаются примерно в течение 10 секунд. Попытка, время которой наступит в этот интервал, ещё может быть отправлена. Повторные попытки также прекращаются, если убрать вебхук из подписки или удалить ресурс вебхука. Если очередь повторных попыток не может принять доставку (она заполнена или размер доставки в очереди, включая данные события, превышает 256 КБ), после сбоя доставка не повторяется, а событие считается недоставленным.

Повторная попытка хранится в очереди не более 8 часов. Если сервис отправки Web3alert остаётся недоступным дольше этого срока, время ожидания истекает и итоговая запись в журнале доставки не появляется.

Блокировка ​

Ответ HTTP 410 Gone на любой попытке сразу блокирует подписку. Пять недоставленных событий подряд для одной подписки и одного ресурса вебхука также блокируют подписку. Событие считается недоставленным, если попытки исчерпаны, его не удалось поставить в очередь на повторную попытку или доставка отклонена. Причиной отклонения может быть неверный URL, секрет подписи неверного формата или HTTP-статус, отличный от 2xx, 410, 429 и 5xx. Ожидающие повторной попытки доставки не входят в счётчик. Успешная доставка обнуляет счётчик этой пары подписки и вебхука. Блокировка также обнуляет счётчик для этой пары подписки и вебхука, поэтому после возобновления начинается новый отсчёт. Счётчик сбрасывается, если за 30 дней не было ни одного нового недоставленного события.

Чтобы возобновить доставки, установите состояние подписки в on в приложении, через PUT /api/subscriptions/:id/state или с помощью MCP-инструмента set_subscription_state.

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

История доставки сохраняется на платных тарифах. Маршруты истории подписок и MCP-инструмент get_delivery_log показывают эти поля в записях каналов вебхуков.

ПолеЗначение
eventIdwebhook-id доставки.
attemptНомер попытки, начиная с 1.
nextAttemptAtВремя в формате ISO, на которое была запланирована следующая попытка в момент создания записи. Если в записи нет запланированной повторной попытки, история REST опускает поле, а MCP-инструмент get_delivery_log возвращает null.

Значение остаётся прежним даже после выполнения или отмены повторной попытки. Чтобы узнать результат доставки, найдите более позднюю запись с тем же eventId. Если повторные попытки прекратились из-за приостановки или удаления подписки либо истёк срок хранения попытки в очереди, Web3alert не создаёт итоговую запись, а по её отсутствию нельзя определить ни исход доставки, ни то, ожидается ли ещё повторная попытка.

reasonCodeЗначение
channel.webhook.retry_scheduledПервая попытка не удалась, запланирована повторная попытка.
channel.webhook.rejectedДоставка вебхука отклонена.
channel.webhook.goneЭндпоинт ответил HTTP 410.
channel.webhook.retries_exhaustedШестая попытка завершилась ошибкой, допускающей повтор.
channel.webhook.retry_queue_fullОчередь повторных попыток не приняла доставку, потому что была заполнена или размер доставки в очереди, включая данные события, превышал 256 КБ. Доставка не повторяется, и событие считается недоставленным.

Статус первой записи учитывает все каналы доставки события. Если другой канал доставил событие, а ошибка вебхука допускает повторную попытку, статус записи события будет delivered, а канал вебхука получит ok: false. В поле reasonCode канала вебхука в записи события указывается channel.webhook.retry_scheduled, если запланирована повторная попытка, или channel.webhook.retry_queue_full, если очередь повторных попыток не может принять доставку (она заполнена или размер доставки в очереди, включая данные события, превышает 256 КБ).

Когда Web3alert фиксирует итоговый результат доставки с повторными попытками, он создаёт отдельную запись с тем же eventId и только каналом вебхука. Статус записи — delivered при успехе, failed при отклонении или исчерпании попыток либо blocked при HTTP 410. Промежуточные сбои, после которых запланирована ещё одна попытка, не создают записей в журнале.

Если очередь повторных попыток не может принять доставку после более поздней попытки, итоговая запись имеет статус failed и содержит channel.webhook.retry_queue_full в канале вебхука.

Сбой системы после записи итогового результата может создать ещё одну итоговую запись для той же доставки. Доставка выполняется как минимум один раз, поэтому группируйте записи по eventId.