Crea endpoint webhook Rivya API firmati, verifica le firme di delivery, ispeziona i tentativi di delivery e invia eventi di test sicuri.

Usa API webhooks quando la tua integrazione ha bisogno che Rivya notifichi il tuo server dopo che una generazione Public API raggiunge uno stato terminale.

Il polling GET /api/v1/generations/{taskId} resta supportato. I webhook aggiungono callback firmati per sistemi di produzione che preferiscono la delivery di eventi.

Scope richiesto

La gestione webhook richiede una chiave API con:

webhooks:manage

Le nuove chiavi create in Settings includono questo scope per impostazione predefinita.

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

La risposta include signing_secret una sola volta:

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

Conserva il secret completo sul tuo server. Se lo perdi, chiama l'endpoint di rotazione e aggiorna il tuo receiver.

Regole URL

Gli URL degli endpoint devono essere HTTPS. Rivya rifiuta URL con credenziali, frammenti, nomi localhost, indirizzi di rete locale, range IP privati, indirizzi loopback e indirizzi riservati.

Rivya invia sempre:

POST
Content-Type: application/json
nessun header di richiesta personalizzato controllato dall'utente
nessun follow automatico dei redirect
un timeout di delivery breve

Eventi

Tipi di evento attuali:

generation.succeeded
generation.failed

I payload webhook usano lo stesso serializer pubblico delle generazioni dell'endpoint di stato.

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

Header di delivery

Ogni delivery include:

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

Input della firma:

${timestamp}.${rawBody}

Algoritmo:

HMAC-SHA256 with the endpoint signing secret

Rifiuta richieste con timestamp troppo vecchi. Una tolleranza di cinque minuti è un default pratico.

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

Verifica 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)

Gestire 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} disabilita l'endpoint. Non elimina la cronologia delle delivery.

Record di delivery

Elenca gli eventi recenti:

GET /api/v1/webhook-events

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

Elenca i tentativi di delivery per un endpoint:

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

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

I record di delivery includono stato, stato HTTP, numero del tentativo, request id, durata, snippet di risposta troncato e campi di errore pubblici.

Evento di test

Invia un payload di test sicuro:

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

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

L'evento di test usa webhook.test. Non crea un task di generazione, non consuma crediti e non include un URL di risultato reale.

Policy di retry

Rivya considera HTTP 2xx come successo.

I fallimenti includono errori di rete, timeout, risposte redirect e risposte non 2xx. Rivya ritenta fino a cinque tentativi:

immediatamente
dopo 1 minuto
dopo 5 minuti
dopo 30 minuti
dopo 2 ore

Dopo l'ultimo tentativo, l'evento viene segnato come failed.

I fallimenti di delivery webhook non cambiano stato della generazione, crediti, rimborsi o cronologia del task.

Checklist di sicurezza

Verifica la firma HMAC prima di elaborare la logica di business.
Rifiuta timestamp obsoleti.
Tratta gli eventi di test separatamente dagli eventi di generazione.
Non registrare nei log signing secret completi.
Restituisci 2xx solo dopo che il tuo receiver ha accettato l'evento.
Mantieni il polling come fallback per la riconciliazione.

API Webhooks