Crie endpoints de webhook assinados da Rivya API, verifique assinaturas de entrega, inspecione tentativas de entrega e envie eventos de teste seguros.

Use webhooks da API quando sua integração precisa que a Rivya notifique seu servidor depois que uma geração da Public API chega a um estado terminal.

Polling com GET /api/v1/generations/{taskId} continua sendo suportado. Webhooks adicionam callbacks assinados para sistemas de produção que preferem entrega por eventos.

Escopo Necessário

O gerenciamento de webhooks exige uma chave de API com:

webhooks:manage

Novas chaves criadas em Configurações incluem esse escopo por padrão.

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

A resposta inclui signing_secret apenas uma vez:

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

Armazene o segredo completo no seu servidor. Se você o perder, chame o endpoint de rotação e atualize seu receiver.

Regras de URL

URLs de endpoint devem usar HTTPS. A Rivya rejeita URLs com credenciais, fragmentos, nomes localhost, endereços de rede local, faixas de IP privado, endereços loopback e endereços reservados.

A Rivya sempre envia:

POST
Content-Type: application/json
nenhum header de solicitação customizado controlado pelo usuário
nenhum seguimento automático de redirecionamento
timeout curto de entrega

Eventos

Tipos de evento atuais:

generation.succeeded
generation.failed

Payloads de webhook usam o mesmo public generation serializer do endpoint de status.

{
  "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 de Entrega

Cada entrega inclui:

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

Entrada da assinatura:

${timestamp}.${rawBody}

Algoritmo:

HMAC-SHA256 with the endpoint signing secret

Rejeite solicitações com timestamps antigos. Uma tolerância de cinco minutos é um padrão prático.

Verificação em 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ção em 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)

Gerenciar 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} desativa o endpoint. Ele não apaga o histórico de entregas.

Registros de Entrega

Liste eventos recentes:

GET /api/v1/webhook-events

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

Liste tentativas de entrega para um endpoint:

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

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

Registros de entrega incluem status, status HTTP, número da tentativa, request id, duração, trecho truncado da resposta e campos públicos de erro.

Evento de Teste

Envie um payload de teste seguro:

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

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

O evento de teste usa webhook.test. Ele não cria uma tarefa de geração, não consome créditos e não inclui uma URL de resultado real.

Política de Nova Tentativa

A Rivya trata HTTP 2xx como sucesso.

Falhas incluem erros de rede, timeout, respostas de redirecionamento e respostas não 2xx. A Rivya tenta novamente até cinco vezes:

imediatamente
após 1 minuto
após 5 minutos
após 30 minutos
após 2 horas

Depois da tentativa final, o evento é marcado como failed.

Falhas de entrega de webhook não alteram status de geração, créditos, reembolsos nem histórico de tarefas.

Checklist de Segurança

Verifique a assinatura HMAC antes de analisar lógica de negócio.
Rejeite timestamps antigos.
Trate eventos de teste separadamente dos eventos de geração.
Não registre segredos completos de assinatura em logs.
Retorne 2xx somente depois que seu receiver aceitar o evento.
Mantenha polling como fallback para reconciliação.

Webhooks da API