Webhooks

Receba notificações em tempo real quando tarefas forem concluídas ou falharem

Visão Geral

Os webhooks permitem que você receba retornos de chamada HTTP quando as suas tarefas de geração de imagem ou vídeo são concluídas. Em vez de verificar periodicamente os resultados, você pode configurar um endpoint de webhook para receber notificações automáticas.

Eventos Disponíveis

task.completedAcionado quando uma tarefa é concluída com sucesso

task.failedAcionado quando uma tarefa falha

GET/api/v1/webhooks

Liste todas as suas configurações de webhook

Resposta

{
  "success": true,
  "data": [
    {
      "id": 1,
      "url": "https://your-server.com/webhook",
      "events": ["job.completed", "job.failed"],
      "status": "active"
    }
  ]
}

POST/api/v1/webhooks

Criar um novo endpoint de webhook

Corpo da Requisição

{
  "url": "https://your-server.com/webhook",
  "events": ["job.completed", "job.failed"],
  "secret_key": "your-secret-key"
}

Campos do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
url	string	Obrigatório	URL do seu endpoint de webhook
events	string[]	Obrigatório	Eventos para se inscrever
secret_key	string	Opcional	Segredo para verificação de assinatura

Resposta

{
  "success": true,
  "data": {
    "id": 1,
    "url": "https://your-server.com/webhook",
    "events": ["job.completed", "job.failed"],
    "status": "active"
  }
}

DELETE/api/v1/webhooks/{id}

Excluir um endpoint de webhook

Resposta

{
  "success": true,
  "data": { "id": 1 }
}

Payload do Webhook

Quando um evento ocorre, enviaremos uma requisição POST para o seu URL de webhook com o seguinte payload:

Cabeçalhos

Cabeçalho	Descrição
X-Webhook-Timestamp	Timestamp Unix da solicitação
X-Webhook-Signature	Assinatura HMAC-SHA256 para verificação

Exemplo de Payload

{
  "event": "job.completed",
  "task_id": "task_xxx",
  "task_type": "image",
  "status": "completed",
  "data": {
    "url": "https://cdn.example.com/image.png",
    "credits_charged": 6
  },
  "timestamp": "2024-12-23T10:00:00Z"
}

Verificação de Assinatura

Verificar a autenticidade de webhooks utilizando HMAC-SHA256

const crypto = require('crypto');

function verifySignature(payload, signature, secret, timestamp) {
  const message = `${timestamp}.${JSON.stringify(payload)}`;
  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
  return `v1=${expectedSig}` === signature;
}