Webhook

Ricevi notifiche in tempo reale quando i task vengono completati o falliscono

Panoramica

I webhook ti consentono di ricevere callback HTTP quando le tue operazioni di generazione immagini o video sono completate. Invece di effettuare polling per ottenere i risultati, puoi configurare un endpoint webhook per ricevere notifiche automatiche.

Eventi Disponibili

task.completedAttivato quando un'attività viene completata con successo

task.failedAttivato quando un'attività non riesce

GET/api/v1/webhooks

Elenca tutte le configurazioni dei tuoi webhook

Risposta

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

POST/api/v1/webhooks

Crea un nuovo endpoint webhook

Corpo della Richiesta

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

Campi del Corpo

Parametro	Tipo	Obbligatorio	Descrizione
url	string	Obbligatorio	L'URL del tuo endpoint webhook
events	string[]	Obbligatorio	Eventi a cui iscriversi
secret_key	string	Facoltativo	Segreto per la verifica della firma

Risposta

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

DELETE/api/v1/webhooks/{id}

Elimina un endpoint webhook

Risposta

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

Payload Webhook

Quando si verifica un evento, invieremo una richiesta POST all'URL del tuo webhook con il seguente payload:

Intestazioni

Intestazione	Descrizione
X-Webhook-Timestamp	Timestamp Unix della richiesta
X-Webhook-Signature	Firma HMAC-SHA256 per la verifica

Payload di esempio

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

Verifica l'autenticità dei webhook utilizzando 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;
}