HypioDocumentação

Gerações

Webhooks

Receba um POST assinado quando uma geração termina ou uma recarga é paga.

Configurar

Em Configurações → Webhooks, cadastre uma URL https pública e escolha os eventos. Até 10 por organização. O segredo começa com whsec_.

Eventos

EventoQuando
generation.completedA geração terminou com sucesso.
generation.failedA geração falhou e a reserva voltou.
credits.topup_succeededUma recarga foi paga e o saldo entrou.

Corpo

generation.completed
{
  "id": "generation.completed:0b7c1e5a-4d2f-4c8e-9a51-6f3d2b8e7c10",
  "type": "generation.completed",
  "created_at": "2026-11-11T14:02:11.000Z",
  "data": {
    "generation_id": "0b7c1e5a-4d2f-4c8e-9a51-6f3d2b8e7c10",
    "kind": "image",
    "model_id": "seedream-5.0-flash",
    "status": "succeeded",
    "output_count": 1,
    "amount_cents": 17,
    "currency": "brl",
    "error": null
  }
}

O id é estável por evento: use-o para descartar entregas repetidas. Em credits.topup_succeeded, data traz checkout_session_id, amount_cents, currency e credits. amount_cents está na moeda de currency (brl, usd ou eur); para somar em reais, use credits, que está sempre em centavos de real.

Headers

HeaderValor
Hypio-Signaturet=<unix>,v1=<hex>
Hypio-Webhook-IdO id do evento.
Hypio-EventO type do evento.

Verificar a assinatura

v1 é o HMAC-SHA256, em hexadecimal, de <t>.<corpo cru> com o segredo como chave. Use o corpo exatamente como chegou e recuse t antigo para barrar reenvio.

import crypto from "node:crypto";

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const received = Buffer.from(parts.v1 ?? "");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && received.length === expected.length && crypto.timingSafeEqual(received, Buffer.from(expected));
}

Entrega e novas tentativas

  • Qualquer resposta 2xx conta como entregue.
  • Responda em até 10 segundos. Depois disso a entrega conta como falha.
  • Falhas são repetidas depois de 30 s, 2 min, 10 min, 30 min, 2 h: 6 tentativas no total.