Webhooks & Signature Verification

Webhooks

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

Visão Geral

Webhooks allow you to receive HTTP callbacks when your image or video generation tasks complete. Instead of polling for results, you can set up a webhook endpoint to receive automatic notifications.

Eventos Disponíveis

job.completedTriggered when a task completes successfully
job.failedTriggered when a task fails

Endpoints da API

GET/api/v1/webhooks

List all your webhook configurations

Exemplo de Resposta:

JSON

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

POST/api/v1/webhooks

Create a new webhook endpoint

Exemplo de Solicitação:

JSON

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

Parâmetros:

urlstringObrigatório
Your webhook endpoint URL
eventsstring[]Obrigatório
Events to subscribe to
secret_keystringOpcional
Secret for signature verification

Exemplo de Resposta:

JSON

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

DELETE/api/v1/webhooks/{id}

Delete a webhook endpoint

Exemplo de Resposta:

JSON

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

Carga do Webhook

Formato das notificações de webhook enviadas para seu endpoint

Cabeçalho	Descrição
X-Nano-Timestamp	Unix timestamp of the request
X-Nano-Signature	HMAC-SHA256 signature for verification

Exemplo de Payload:

JSON

{
  "id": "job.completed:task_xxx",
  "type": "job.completed",
  "created_at": 1734948000,
  "data": {
    "task_id": "task_xxx",
    "model": "veo3",
    "status": "completed",
    "video_url": "https://cdn.example.com/video.mp4"
  }
}

Verificação de Assinatura

javascript

const crypto = require('crypto');

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

Cabeçalho

Descrição

X-Nano-Timestamp

Unix timestamp of the request

X-Nano-Signature

HMAC-SHA256 signature for verification

{ "id": "job.completed:task_xxx", "type": "job.completed", "created_at": 1734948000, "data": { "task_id": "task_xxx", "model": "veo3", "status": "completed", "video_url": "https://cdn.example.com/video.mp4" } }