Vytvářejte podepsané webhook endpointy 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.

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

Požadovaný scope

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

webhooks:manage

Nové klíče vytvořené v Settings obsahují tento scope ve výchozím nastavení.

Vytvoření endpointu

POST /api/v1/webhooks

curl https://rivya.ai/api/v1/webhooks \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Produkční 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": "Produkční 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í request headery řízené uživatelem
žádné automatické následování redirectů
krátký timeout doručení

Události

Aktuální typy událostí:

generation.succeeded
generation.failed

Payloady webhooků používají stejný veřejný serializer generování jako endpoint stavu.

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

Headery 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 s podpisovým secretem endpointu

Odmítejte požadavky se zastaralými timestampy. 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ý úryvek odpovědi 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, timeout, redirect odpovědi 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, refundace ani historii úlohy.

Bezpečnostní checklist

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

API Webhooks