Створюйте підписані кінцеві точки webhook Rivya API, перевіряйте підписи доставок, переглядайте спроби доставки та надсилайте безпечні тестові події.

Використовуйте API webhooks, коли вашій інтеграції потрібно, щоб Rivya повідомляла ваш сервер після того, як генерація Public API досягне термінального стану.

Опитування GET /api/v1/generations/{taskId} усе ще підтримується. Webhooks додають підписані callback-запити для production-систем, які віддають перевагу доставці подій.

Потрібний scope

Керування webhooks потребує API-ключа з:

webhooks:manage

Нові ключі, створені в налаштуваннях, містять цей scope за замовчуванням.

Створення 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 кінцевих точок мають бути HTTPS. Rivya відхиляє URL з обліковими даними, фрагментами, іменами localhost, адресами локальної мережі, приватними IP-діапазонами, адресами зворотної петлі та зарезервованими адресами.

Rivya завжди надсилає:

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

Події

Поточні типи подій:

generation.succeeded
generation.failed

Payloads webhook використовують той самий публічний серіалізатор генерації, що й 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

Відхиляйте запити із застарілими часовими позначками. Практичне стандартне вікно - п'ять хвилин.

Перевірка 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, тривалість, скорочений фрагмент відповіді та публічні поля помилки.

Тестова подія

Надішліть безпечний тестовий 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 успіхом.

Помилки включають мережеві збої, таймаути, відповіді з перенаправленням і відповіді не 2xx. Rivya повторює до п'яти спроб:

негайно
через 1 хвилину
через 5 хвилин
через 30 хвилин
через 2 години

Після останньої спроби подію позначають як failed.

Збої доставки webhook не змінюють статус генерації, кредити, повернення коштів або історію задачі.

Безпековий checklist

Перевіряйте HMAC-підпис перед розбором бізнес-логіки.
Відхиляйте застарілі часові позначки.
Обробляйте тестові події окремо від подій генерації.
Не записуйте повні секрети підпису в журнали.
Повертайте 2xx лише після того, як ваш приймач прийняв подію.
Залишайте опитування як запасний механізм для звірки.

API Webhooks