Webhooks

Recibe notificaciones en tiempo real cuando las tareas se completen o fallen.

Resumen

Los webhooks te permiten recibir devoluciones de llamada HTTP cuando tus tareas de generación de imágenes o videos se completan. En lugar de consultar periódicamente por los resultados, puedes configurar un endpoint de webhook para recibir notificaciones automáticas.

Eventos Disponibles

task.completedActivado cuando una tarea se completa exitosamente

task.failedActivado cuando una tarea falla

GET/api/v1/webhooks

Lista todas tus configuraciones de webhook

Respuesta

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

POST/api/v1/webhooks

Crear un nuevo punto de enlace webhook

Cuerpo de la Solicitud

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

Campos del Cuerpo

Parámetro	Tipo	Obligatorio	Descripción
url	string	Necesario	La URL de tu endpoint de webhook
events	string[]	Necesario	Eventos a los que suscribirse
secret_key	string	Opcional	Secreto para verificación de firmas

Respuesta

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

DELETE/api/v1/webhooks/{id}

Eliminar un endpoint de webhook

Respuesta

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

Carga de Webhook

Cuando ocurre un evento, enviaremos una solicitud POST a la URL de tu webhook con el siguiente contenido:

Encabezados

Encabezado	Descripción
X-Webhook-Timestamp	Marca de tiempo Unix de la solicitud
X-Webhook-Signature	Firma HMAC-SHA256 para verificación

Ejemplo de Carga Útil

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

Verificación de Firmas

Verifica la autenticidad de los webhooks mediante 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;
}