Вебхуки — Справочник API

Регистрация и тестирование эндпоинтов доставки уведомлений.

Сгенерировано из openapi.yaml во время сборки. Базовый URL https://api.tenergy.me/v1 или https://api-nile.tenergy.me/v1 в сети Nile (Окружения). Каждый запрос ниже подписывается в соответствии с разделом Аутентификация, если в строке Аутентификация не указано иное.

Список эндпоинтов доставки

GET /v1/webhooks · listWebhooks

Аутентификация: API-ключ (HMAC).

Поле secret никогда не возвращается этим эндпоинтом.

Ответы

Поля ответа

Регистрация эндпоинта доставки

POST /v1/webhooks · createWebhook

Аутентификация: API-ключ (HMAC).

Возвращает secret, который показывается ровно один раз. Им подписывается каждое уведомление на этот адрес — сохраните его сразу; при утере выполните ротацию секрета, а не повторную регистрацию.

Не более двух эндпоинтов на аккаунт: один primary (основной) и один backup (резервный). Доставка не является веерной (fan-out) — каждое событие сначала направляется на основной, и переключается на резервный только после исчерпания всех повторных попыток на основном. Первый созданный эндпоинт автоматически становится основным.

Требования к URL, проверяемые при создании и изменении: только https; должен разрешаться в публичный IP-адрес (loopback, RFC 1918, link-local вроде 169.254.169.254 и другие немаршрутизируемые диапазоны отклоняются); запрещены учетные данные в URL; длина не более 2048 символов.

Полный каталог событий, структура полезной нагрузки, схема подписи и расписание повторов описаны в разделе Вебхуки.

Тело запроса

JSON (WebhookRequest), обязательно.

Пример тела запроса из контракта (значения для иллюстрации):

{
  "url": "https://acme.example/hooks/tenergy",
  "role": "primary",
  "events": ["order.confirmed","order.failed","balance.credited"]
}

Ответы

Поля ответа

Чтение одного эндпоинта

GET /v1/webhooks/{webhookId} · getWebhook

Аутентификация: API-ключ (HMAC).

Параметры

Ответы

Поля ответа (WebhookEndpoint)

Редактирование эндпоинта

PATCH /v1/webhooks/{webhookId} · updateWebhook

Аутентификация: API-ключ (HMAC).

Изменение url, events, is_active и/или role. Отправка {"role": "primary"} на резервный эндпоинт меняет роли местами в рамках одной атомарной транзакции. Новый URL проверяется повторно. Флаг is_active: false приостанавливает отправку без удаления конфигурации; пауза основного эндпоинта не переключает трафик автоматически на резервный (для этого используйте смену ролей).

Параметры

Тело запроса

JSON (WebhookPatch), обязательно.

Ответы

Поля ответа (WebhookEndpoint)

Удаление эндпоинта

DELETE /v1/webhooks/{webhookId} · deleteWebhook

Аутентификация: API-ключ (HMAC).

Полное удаление; освобождает занятую роль. Недоставленные события для данного эндпоинта отбрасываются.

Параметры

Ответы

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

POST /v1/webhooks/{webhookId}/rotate-secret · rotateWebhookSecret

Аутентификация: API-ключ (HMAC).

Возвращает новый секрет один раз. Он вступает в силу немедленно для последующих доставок без периода пересечения: обновите секрет на стороне вашего сервиса перед вызовом эндпоинта либо будьте готовы к краткосрочным ошибкам проверки подписи повторных отправок. У каждого эндпоинта свой секрет — ротация на основном не затрагивает резервный.

Параметры

Ответы

Поля ответа

Отправка тестового события

POST /v1/webhooks/{webhookId}/test · testWebhook

Аутентификация: API-ключ (HMAC).

Отправляет синтетическое событие на эндпоинт и возвращает ответ вашего сервера. Полезная нагрузка подписывается стандартной подписью и содержит флаг "test": true на верхнем уровне, поэтому обработчик, проверяющий этот флаг, не станет выполнять рабочие действия.

Тестовые доставки не повторяются при ошибке и не сохраняются в журнале доставок.

Параметры

Тело запроса

JSON.

Ответы

Поля ответа

Журнал доставок одного эндпоинта

GET /v1/webhooks/{webhookId}/deliveries · listWebhookDeliveries

Аутентификация: API-ключ (HMAC).

Все события в очереди на доставку для данного эндпоинта (новые сначала): тип события, число попыток, статус, последний HTTP-код вашего сервера и время следующей попытки. Тестовые доставки не отображаются. Требуется scope webhooks.read или сессия панели с ролью viewer. Чужой эндпоинт возвращает 404.

Параметры

Ответы

Поля ответа

Пример ответа 200 из контракта (значения для иллюстрации):

{
  "data": [
    {
      "id": "dlv_01K5YA1B2C3D4E5F6G7H8J9K0M",
      "event_id": "evt_01K5YA1B2C3D4E5F6G7H8J9K0N",
      "event": "order.confirmed",
      "attempt": 2,
      "state": "failed",
      "response_status": 502,
      "error": null,
      "next_attempt_at": "2026-09-25T10:31:00.000Z",
      "delivered_at": null,
      "created_at": "2026-09-25T10:30:00.000Z",
      "updated_at": "2026-09-25T10:30:30.000Z"
    }
  ],
  "next_cursor": null
}