Vytvářejte podepsané koncové body webhooků Rivya API, ověřujte podpisy doručení, kontrolujte pokusy o doručení a posílejte bezpečné testovací události.

Použijte API webhooky, když vaše integrace potřebuje, aby Rivya upozornila váš server po dosažení koncového stavu generování přes Public API.

Dotazování GET /api/v1/generations/{taskId} zůstává podporované. Webhooky přidávají podepsaná zpětná volání pro produkční systémy, které preferují doručování událostí.

Požadované oprávnění

Správa webhooků vyžaduje API klíč s:

webhooks:manage

Nové klíče vytvořené v Nastavení obsahují toto oprávnění ve výchozím nastavení.

Vytvoření koncového bodu

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"]
  }'

Odpověď obsahuje signing_secret pouze jednou:

{
  "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
}

Uložte celý secret na svém serveru. Pokud ho ztratíte, zavolejte endpoint pro rotaci a aktualizujte svůj přijímač.

Pravidla URL

URL endpointu musí být HTTPS. Rivya odmítá URL s přihlašovacími údaji, fragmenty, názvy localhost, adresami lokální sítě, privátními rozsahy IP, loopback adresami a rezervovanými adresami.

Rivya vždy posílá:

POST
Content-Type: application/json
žádné vlastní hlavičky požadavku řízené uživatelem
žádné automatické následování přesměrování
krátký časový limit doručení

Události

Aktuální typy událostí:

generation.succeeded
generation.failed

Webhook payload používá stejný veřejný serializer generování jako status 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
    }
  }
}

Hlavičky doručení

Každé doručení obsahuje:

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_...

Vstup podpisu:

${timestamp}.${rawBody}

Algoritmus:

HMAC-SHA256 with the endpoint signing secret

Odmítejte požadavky se zastaralými časovými razítky. Praktická výchozí tolerance je pět minut.

Ověření v JavaScriptu

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"));
}

Ověření v Pythonu

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)

Správa endpointů

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 deaktivuje. Neodstraní historii doručení.

Záznamy doručení

Vypište nedávné události:

GET /api/v1/webhook-events

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

Vypište pokusy o doručení pro endpoint:

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

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

Záznamy doručení obsahují status, HTTP status, číslo pokusu, request id, dobu trvání, zkrácený response snippet a veřejná pole chyby.

Testovací událost

Pošlete bezpečný testovací payload:

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

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

Testovací událost používá webhook.test. Nevytváří úlohu generování, nespotřebovává kredity a neobsahuje skutečné URL výsledku.

Pravidla opakování

Rivya považuje HTTP 2xx za úspěch.

Selhání zahrnují síťové chyby, časový limit, odpovědi s přesměrováním a odpovědi mimo 2xx. Rivya opakuje až pět pokusů:

okamžitě
po 1 minutě
po 5 minutách
po 30 minutách
po 2 hodinách

Po posledním pokusu se událost označí jako failed.

Selhání doručení webhooku nemění stav generování, kredity, vrácení kreditů ani historii úlohy.

Bezpečnostní checklist

Před parsováním obchodní logiky ověřte HMAC podpis.
Odmítejte zastaralá časová razítka.
Zpracovávejte testovací události odděleně od událostí generování.
Nelogujte celé signing secrets.
Vraťte 2xx až poté, co váš přijímač událost přijal.
Ponechte dotazování jako záložní cestu pro rekonciliaci.

API Webhooks