Webhooks

TEnergy поддерживает отправку асинхронных уведомлений о событиях на ваш сервер через Webhooks. Состояния заказов совпадают с API и кабинетом: created → paid → allocating → delegated → confirmed → active → expired | reclaimed, с терминальными ветками ошибок failed и refunded. Частичное исполнение не является отдельным статусом, а выражается флагом partial: true и объемом delivered_amount.

Управление эндпоинтами

• Два эндпоинта: основной и резервный. Вы можете настроить один primary (основной) и один backup (резервный) эндпоинт. Все события отправляются на основной; резервный подключается только после исчерпания всех попыток на основном. Каждое событие сохраняет постоянный delivery_id при переходе между эндпоинтами для корректной дедупликации.
• Бесшовная смена URL без простоя: зарегистрируйте новый URL с ролью backup, проверьте тестовой отправкой, а затем вызовите PATCH и установите role: "primary".
• Локальная разработка: используйте публичный туннель (например, ngrok) — валидатор URL отклоняет локальные и приватные IP, поэтому зарегистрировать localhost напрямую нельзя.

Типы событий

• Отказ — это тоже событие: мы отправляем order.failed. Уведомление только об успехах вынуждает клиентов опрашивать API для выявления сбоев. Маршрутизируйте логику по event и игнорируйте неизвестные типы — добавление новых событий не должно ломать ваш сервис.
• order.confirmed: обязательно проверяйте partial. При частичном исполнении приходит это же событие с флагом partial: true, объемом delivered_amount < amount и суммой возврата refunded_amount_sun.
• delegate_hashes: массив транзакций в сети (при наборе объема из нескольких кошельков). Каждый хэш верифицируется в блокчейне перед отправкой вебхука, отправка несуществующих хэшей исключена.

Структура полезной нагрузки (Payload)

Общая структура для всех событий:

{
  "event": "order.confirmed",
  "event_id": "evt_01J9ZB3F5HJK",
  "event_version": 1,
  "created_at": "2026-09-11T18:04:08.100Z",
  "account_id": "acc_01J9Z4K2M7Q8",
  "network": "mainnet",
  "test": false,
  "data": { }
}

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

Выполняйте дедупликацию строго по X-Event-Id (или event_id), а не по X-Delivery-Id.

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

Спецификация: X-API-SIGN = base64(HMAC_SHA256(endpoint_secret, X-API-TIMESTAMP + "." + raw_body)), вычисляется строго над сырыми байтами тела запроса в том виде, в котором они были получены — любое изменение форматирования JSON ломает подпись. Допустимое окно рассинхронизации часов: ±300 секунд.

import crypto from 'node:crypto';
const MAX_SKEW_SECONDS = 300;

export function verifyWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-api-timestamp'], signature = headers['x-api-sign'];
  if (!timestamp || !signature) return false;
  const skew = Math.abs(Date.now() / 1000 - Number(timestamp));   // защита от повторов
  if (!Number.isFinite(skew) || skew > MAX_SKEW_SECONDS) return false;
  const signed = Buffer.concat([Buffer.from(`${timestamp}.`), rawBody]);
  const expected = crypto.createHmac('sha256', secret).update(signed).digest('base64');
  const a = Buffer.from(expected), b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Три правила проверки:

1. Сначала проверка подписи, затем парсинг: не передавайте непроверенный JSON в бизнес-логику.
2. Сравнение за константное время: используйте crypto.timingSafeEqual или hmac.compare_digest для защиты от атак по времени.
3. Проверка метки времени: отклоняйте запросы с разницей более 300 секунд для защиты от атак повторного воспроизведения.

Расписание повторных попыток

Доставка строится по принципу At-least-once (как минимум один раз). Ваш сервер должен ответить статусом 2xx; любой статус, отличный от 2xx, обрыв соединения или ответ дольше 10 секунд считается сбоем и запускает повторные попытки:

Общий интервал повторов составляет около 11 часов. Для сверхкоротких тиров (5m, 15m) повторы прекращаются после 4 попытки (около 4 минут). Если основной эндпоинт исчерпал попытки и настроен резервный, доставка переключается на резервный, и расписание запускается с 1 попытки. Тестовые события никогда не повторяются.

Требования к сервису-получателю

1. Дедупликация по event_id: сохраняйте полученные идентификаторы; повторный запрос должен возвращать 200 без повторного выполнения бизнес-логики.
2. Проверяйте HMAC перед отгрузкой: никогда не исполняйте заказ клиента до успешной проверки подписи вебхука.
3. Возвращайте 2xx только после надежного сохранения события: подтверждение до сохранения превратит наш ретрай в утерянное вами событие.
4. Не полагайтесь исключительно на вебхуки: периодически выполняйте сверку по расписанию через GET /v1/orders?status=confirmed&created_after=….
5. Отвечайте в течение 10 секунд: принимайте событие, сохраняйте в очередь и сразу возвращайте 200; тяжелую обработку выполняйте в фоне.