Webhooks

Um webhook informa seu servidor quando algo acontece, como um vídeo terminando. Ele evita que você faça sondeios GET /v1/job/{id}. Webhooks são gerenciados com a mesma chave de API que o restante do API, sob https://reigniter.ai/api/webhooks.

Eventos

Evento	Enviado quando
video.completed	Renderização concluída. O payload download_url, um link que funciona por 7 dias.
video.failed	Uma renderização falhou. Uma renderização que você cancela não envia isso.
training.invited	Um aluno recebia um módulo e enviava sua página de treinamento.
training.completed	Um aprendiz nomeado terminou um módulo. A carga útil tem a pontuação (marcada pelo servidor), passed, e sua página de resultados.
training.passed / training.failed	Enviado com training.completed, contra a nota de aprovação do módulo. Ficar sem tempo é reprovação.
training.overdue	Um aluno não terminou até a data prevista. Uma vez por convite.
training.certificate_expiring	Um certificado expira em até 30 dias. Uma vez por certificado.
post.published	Uma postagem foi publicada em YouTube, TikTok, LinkedIn, Facebook ou Instagram. O payload tem a plataforma, a conta e url, o link para a postagem quando a plataforma fornece um.
post.failed	Uma postagem não poderia ser publicada. reason é a resposta da plataforma em palavras claras.
credits.low	O saldo caiu para 10 créditos ou menos. Uma vez por drop.
credits.purchased	Créditos foram adicionados à conta.
subscription.created	Uma assinatura de plano foi iniciada.
subscription.canceled	Uma assinatura de plano foi cancelada.
user.signup	A conta foi criada.
user.onboarded	A conta terminou de ser integrada.

GET /api/webhooks/events devolve essa lista.

Monte um webhook

1. Construa um endpoint no seu servidor que aceite POST solicitações com um corpo JSON e responda 2xx rapidamente. Ele deve ser acessível pela internet pública. Endereços de rede privada e local são recusados.

2. Assine em um evento. Um webhook escuta um evento; crie um para cada evento que você precisar.

   curl

   curl https://reigniter.ai/api/webhooks/hooks \
     -H "Authorization: Bearer $REIGNITER_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "event": "video.completed",
       "webhook_url": "https://hooks.example.com/reignitor",
       "description": "Post finished videos to our CMS"
     }'

   JavaScript

   const res = await fetch('https://reigniter.ai/api/webhooks/hooks', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${process.env.REIGNITER_API_KEY}`,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
       event: 'video.completed',
       webhook_url: 'https://hooks.example.com/reignitor',
       description: 'Post finished videos to our CMS',
     }),
   });
   const { hook, secret } = await res.json();

   Python

   res = requests.post(
       "https://reigniter.ai/api/webhooks/hooks",
       headers={"Authorization": f"Bearer {os.environ['REIGNITER_API_KEY']}"},
       json={
           "event": "video.completed",
           "webhook_url": "https://hooks.example.com/reignitor",
           "description": "Post finished videos to our CMS",
       },
   )
   data = res.json()
   hook, secret = data["hook"], data["secret"]

3. Armazene o secret da resposta 201. Você precisa dele para verificar assinaturas.

   Cuidado

   O segredo de assinatura é mostrado uma vez. Leituras posteriores retornam has_secret: true em vez disso. Se você perder, apague o webhook e crie novamente.

4. Envie um teste. POST /api/webhooks/hooks/{id}/test envia um evento de ping assinado para sua URL e informa o que seu endpoint respondeu:

   { "delivered": true, "status": 200 }

Assinar o mesmo evento e URL novamente não cria um duplicado. Ele retorna o webhook existente com reused: true e o liga novamente.

Como é uma entrega

Cada entrega é um POST com um corpo JSON:

{
  "event": "video.completed",
  "payload": {
    "job_id": "7d2e4b10-5c3a-4f8e-a1b2-9c0d8e7f6a54",
    "user_id": "3f1c2a9e-8b7d-4c1e-9f0a-2d6b5e4c3a21",
    "output_url": "https://cdn.example.com/exports/7d2e4b10.mp4",
    "canvas_id": null,
    "scene_count": 4,
    "scenes_failed": 0,
    "credits_charged": 12
  },
  "emitted_at": "2026-09-25T10:15:00.000Z",
  "delivery_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
}

video.failed carrega job_id, user_id, canvas_id e um reason.

Compare payload.job_id com o job_id que você recebeu de POST /v1/render.

E estes cabeçalhos:

Cabeçalho	Valor
X-Reigniter-Event	O nome do evento.
X-Reigniter-Delivery	Um ID único para essa entrega. Permanece igual quando uma entrega é tentada novamente.
X-Reigniter-Timestamp	Hora Unix, em segundos, quando a entrega foi assinada.
X-Reigniter-Signature	sha256= e o hexágono HMAC-SHA256 de {timestamp}.{raw body}, vinculado ao seu segredo.

Verifique a assinatura

Verifique cada entrega antes de confiar nela:

1. Leia o corpo bruto do pedido antes de qualquer JSON analisar.
2. Construa a linha {X-Reigniter-Timestamp}.{raw body}.
3. Calcule o HMAC-SHA256 dele com seu segredo, como hexadecimal, e adicione sha256= na frente.
4. Compare com X-Reigniter-Signature usando uma comparação em tempo constante.
5. Rejeite a entrega se o carimbo de tempo tiver mais de 5 minutos.

JavaScript

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyReigniterWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-banshea-timestamp'];
  const received = headers['x-banshea-signature'] ?? '';
  if (!timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = 'sha256=' + createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(received);
  return a.length === b.length && timingSafeEqual(a, b);
}

Python

import hashlib, hmac, time

def verify_reignitor_webhook(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers.get("X-Reigniter-Timestamp")
    received = headers.get("X-Reigniter-Signature", "")
    if not timestamp or abs(time.time() - int(timestamp)) > 300:
        return False

    signed = f"{timestamp}.".encode() + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received)

Entrega e tentativas repetidas

• Cada entrega espera até 10 segundos para que seu endpoint responda.
• Um 5xx, um 429, um timeout ou um erro de rede é tentado novamente, com até 3 tentativas no total, com cerca de um segundo de intervalo.
• Qualquer outra 4xx não é retentada.
• As tentativas mantêm o mesmo X-Reigniter-Delivery. Use para ignorar uma entrega que você já lidou com isso.
• Após 20 entregas falhadas seguidas, o webhook é desligado. GET /api/webhooks/hooks mostra active: false e o último erro em last_status. Corrija seu endpoint, depois ligue-o novamente com PATCH /api/webhooks/hooks/{id} e { "active": true }.

Responda 2xx assim que guardar a entrega e faça um trabalho lento depois.

Nota

Webhooks são uma conveniência, não uma garantia. Se uma entrega for perdida, GET /v1/job/{id} sempre tem o estado atual de um render.

Gerencie webhooks

Método	Caminho	O que ele faz
GET	/api/webhooks/events	Nomes de eventos de lista e o esquema de assinatura
GET	/api/webhooks/hooks	Liste seus webhooks
POST	/api/webhooks/hooks	Crie um webhook
PATCH	/api/webhooks/hooks/{id}	Pausa, retomar ou alterar a URL ou descrição
DELETE	/api/webhooks/hooks/{id}	Exclua um webhook
POST	/api/webhooks/hooks/{id}/test	Envie um ping assinado

Uma conta pode ter até 25 webhooks. Formulários completos de solicitação e resposta estão na referência do endpoint.