Создавайте подписанные endpoints вебхуков Rivya API, проверяйте подписи доставок, изучайте попытки доставки и отправляйте безопасные тестовые события.

Используйте API-вебхуки, когда вашей интеграции нужно, чтобы Rivya уведомляла ваш сервер после перехода генерации Public API в конечное состояние.

Опрос GET /api/v1/generations/{taskId} по-прежнему поддерживается. Вебхуки добавляют подписанные callbacks для production-систем, которым удобнее доставка событий.

Требуемая область доступа

Для управления вебхуками нужен API-ключ с:

webhooks:manage

Новые ключи, созданные в настройках, по умолчанию включают эту область доступа.

Создание endpoint

POST /api/v1/webhooks

curl https://rivya.ai/api/v1/webhooks \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production webhook",
    "url": "https://example.com/rivya/webhook",
    "event_types": ["generation.succeeded", "generation.failed"]
  }'

Ответ включает signing_secret только один раз:

{
  "id": "whend_...",
  "object": "webhook_endpoint",
  "name": "Production webhook",
  "url": "https://example.com/rivya/webhook",
  "event_types": ["generation.succeeded", "generation.failed"],
  "status": "active",
  "secret_preview": "whsec_12...abc123",
  "signing_secret": "whsec_...",
  "last_success_at": null,
  "last_failure_at": null,
  "failure_count": 0,
  "created_at": "2026-05-11T00:00:00.000Z",
  "updated_at": "2026-05-11T00:00:00.000Z",
  "disabled_at": null,
  "revoked_at": null
}

Храните полный секрет на своем сервере. Если вы его потеряете, вызовите endpoint ротации и обновите приемник.

Правила URL

URL endpoint должен использовать HTTPS. Rivya отклоняет URL с учетными данными, fragments, именами localhost, адресами локальной сети, диапазонами private IP, loopback-адресами и зарезервированными адресами.

Rivya всегда отправляет:

POST
Content-Type: application/json
без пользовательских заголовков запроса
без автоматического следования redirect
короткий timeout доставки

События

Текущие типы событий:

generation.succeeded
generation.failed

Payload вебхуков использует тот же публичный сериализатор генерации, что и endpoint статуса.

{
  "id": "evt_...",
  "type": "generation.succeeded",
  "api_version": "2026-05-11",
  "created_at": "2026-05-11T00:00:00.000Z",
  "data": {
    "generation": {
      "id": "task_public_id",
      "status": "succeeded",
      "model": "z-image",
      "reserved_credits": 1,
      "final_credits": 1,
      "created_at": "2026-05-11T00:00:00.000Z",
      "updated_at": "2026-05-11T00:01:00.000Z",
      "result": {
        "primary_url": "https://...",
        "urls": ["https://..."]
      },
      "error": null
    }
  }
}

Headers доставки

Каждая доставка включает:

Rivya-Webhook-Id: evt_...
Rivya-Webhook-Timestamp: 1778467200
Rivya-Webhook-Signature: v1=<hex-hmac-sha256>
Rivya-Webhook-Attempt: 1
Rivya-Webhook-Endpoint-Id: whend_...
Rivya-Request-Id: req_...

Входные данные подписи:

${timestamp}.${rawBody}

Алгоритм:

HMAC-SHA256 with the endpoint signing secret

Отклоняйте запросы с устаревшими timestamps. Практичный default - допуск в пять минут.

Проверка на JavaScript

import crypto from "node:crypto";

function verifyRivyaWebhook({ rawBody, headers, signingSecret }) {
  const timestamp = headers["rivya-webhook-timestamp"];
  const signature = headers["rivya-webhook-signature"] || "";
  const actual = signature.split(",").find((part) => part.startsWith("v1="))?.slice(3);
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  if (!actual) return false;
  return crypto.timingSafeEqual(Buffer.from(actual, "hex"), Buffer.from(expected, "hex"));
}

Проверка на Python

import hmac
import hashlib

def verify_rivya_webhook(raw_body: str, headers: dict, signing_secret: str) -> bool:
    timestamp = headers.get("rivya-webhook-timestamp", "")
    signature = headers.get("rivya-webhook-signature", "")
    actual = next((part[3:] for part in signature.split(",") if part.startswith("v1=")), "")
    expected = hmac.new(
        signing_secret.encode(),
        f"{timestamp}.{raw_body}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return bool(actual) and hmac.compare_digest(actual, expected)

Управление endpoints

GET /api/v1/webhooks
GET /api/v1/webhooks/{endpointId}
PATCH /api/v1/webhooks/{endpointId}
DELETE /api/v1/webhooks/{endpointId}
POST /api/v1/webhooks/{endpointId}/rotate-secret

curl https://rivya.ai/api/v1/webhooks \
  -H "Authorization: Bearer rvya_sk_..."

curl https://rivya.ai/api/v1/webhooks/whend_... \
  -H "Authorization: Bearer rvya_sk_..."

curl -X PATCH https://rivya.ai/api/v1/webhooks/whend_... \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"status":"disabled"}'

curl -X POST https://rivya.ai/api/v1/webhooks/whend_.../rotate-secret \
  -H "Authorization: Bearer rvya_sk_..."

DELETE /api/v1/webhooks/{endpointId} отключает endpoint. Он не удаляет историю доставок.

Записи доставок

Получить список недавних событий:

GET /api/v1/webhook-events

curl https://rivya.ai/api/v1/webhook-events \
  -H "Authorization: Bearer rvya_sk_..."

Получить список попыток доставки для endpoint:

GET /api/v1/webhooks/{endpointId}/deliveries

curl https://rivya.ai/api/v1/webhooks/whend_.../deliveries \
  -H "Authorization: Bearer rvya_sk_..."

Записи доставок включают status, HTTP status, номер попытки, request id, duration, усеченный фрагмент ответа и публичные поля ошибок.

Тестовое событие

Отправьте безопасный тестовый payload:

POST /api/v1/webhooks/{endpointId}/test

curl -X POST https://rivya.ai/api/v1/webhooks/whend_.../test \
  -H "Authorization: Bearer rvya_sk_..."

Тестовое событие использует webhook.test. Оно не создает задачу генерации, не расходует кредиты и не включает реальный URL результата.

Политика повторов

Rivya считает HTTP 2xx успехом.

К неудачам относятся сетевые ошибки, timeout, ответы redirect и ответы не из диапазона 2xx. Rivya повторяет доставку до пяти попыток:

немедленно
через 1 минуту
через 5 минут
через 30 минут
через 2 часа

После последней попытки событие помечается как failed.

Ошибки доставки вебхука не меняют статус генерации, кредиты, возвраты или историю задачи.

Чеклист безопасности

Проверяйте HMAC-подпись до разбора бизнес-логики.
Отклоняйте устаревшие timestamps.
Обрабатывайте тестовые события отдельно от событий генерации.
Не логируйте полные signing secrets.
Возвращайте 2xx только после того, как ваш приемник принял событие.
Сохраняйте polling как fallback для сверки.

API-вебхуки