Webhooks

Recevez des notifications en temps réel lors de la réussite ou de l'échec des tâches.

Vue d'ensemble

Les webhooks vous permettent de recevoir des rappels HTTP lorsque vos tâches de génération d'images ou de vidéos sont terminées. Plutôt que d'interroger régulièrement pour obtenir les résultats, vous pouvez configurer un point de terminaison webhook pour recevoir des notifications automatiques.

Événements disponibles

task.completedDéclenché lorsqu'une tâche s'achève avec succès

task.failedDéclenché lorsqu'une tâche échoue

GET/api/v1/webhooks

Listez toutes vos configurations de webhooks

Réponse

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

POST/api/v1/webhooks

Créer un nouveau point de terminaison webhook

Corps de la requête

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

Champs de corps

Paramètre	Type	Obligatoire	Description
url	string	Obligatoire	URL de votre point de terminaison webhook
events	string[]	Obligatoire	Événements auxquels s'abonner
secret_key	string	Facultatif	Clé secrète pour la vérification de signature

Réponse

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

DELETE/api/v1/webhooks/{id}

Supprimer un point de terminaison de webhook

Réponse

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

Charge utile de Webhook

Lorsqu'un événement se produit, nous enverrons une requête POST à votre URL de webhook avec le payload suivant :

En-têtes

En-tête	Description
X-Webhook-Timestamp	Horodatage Unix de la requête
X-Webhook-Signature	Signature HMAC-SHA256 pour vérification

Exemple de Chargement Utile

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

Vérification de signature

Vérifiez l'authenticité des webhooks en utilisant 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;
}