Документация Rivya AI

API-вебхуки

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

Последняя проверка: 2026/05/11

Используйте 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 для сверки.

Связанные страницы

Rivya TypeScript SDK

Используйте beta Rivya TypeScript SDK для вызова Public API v1: моделей, генераций, файлов, кредитов, вебхуков и Chat, включая SSE-стриминг.

Обзор Rivya API

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

Содержание

Требуемая область доступа
Создание endpoint
Правила URL
События
Headers доставки
Проверка на JavaScript
Проверка на Python
Управление endpoints
Записи доставок
Тестовое событие
Политика повторов
Чеклист безопасности
Связанные страницы