Skip to main content

​
Vue d’ensemble

Au lieu d’interroger GET /jobs/{id} à répétition, vous pouvez fournir une URL de webhook pour recevoir une requête POST lorsque votre job est terminé. C’est plus efficace et cela réduit le nombre d’appels API inutiles.

​
Utiliser les webhooks

Ajoutez l’en-tête X-Webhook-URL à toute requête de génération. Lorsque le job atteint un état terminal (completed, failed ou cancelled), l’API envoie une requête POST à votre URL avec les données complètes du job. 
// npm install @krea-ai/sdk
import { Krea } from "@krea-ai/sdk";

const krea = new Krea({ apiKey: process.env.KREA_API_KEY });

const job = await krea.image(
  "bfl/flux-1-dev",
  {
    prompt: "a serene mountain landscape at sunset",
    width: 1024,
    height: 576
  },
  { webhookUrl: "https://your-server.com/webhook" }
);

console.log(`Job ID: ${job.job_id}`);
// Your webhook will receive the results when complete

​
Charge utile du webhook

Lorsque le job est terminé, votre URL de webhook reçoit une requête POST contenant les données du job : 
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "created_at": "2025-01-15T10:30:00.000Z",
  "completed_at": "2025-01-15T10:30:05.000Z",
  "result": {
    "urls": ["https://..."]
  }
}

​
Bonnes pratiques

Répondez rapidement — Retournez rapidement un code de statut 2xx. Traitez les données du webhook de manière asynchrone si nécessaire.
Validez la charge utile — Vérifiez que le job_id correspond à un job que vous avez initié avant de traiter les résultats.
  • Utilisez des points de terminaison HTTPS pour la sécurité
  • Implémentez l’idempotence en cas de livraisons dupliquées
  • Journalisez les réceptions de webhooks pour faciliter le débogage

​
Webhooks vs polling

ApprocheAvantagesInconvénients
WebhooksNotifications en temps réel, moins d’appels APINécessite un point de terminaison public
PollingFonctionne partout, aucun serveur nécessairePlus d’appels API, léger délai
Utilisez les webhooks lorsque vous disposez d’un serveur capable de recevoir des requêtes HTTP. Utilisez le polling pour les applications côté client ou lorsque vous ne pouvez pas exposer un point de terminaison public.

​
Étapes suivantes

Cycle de vie des jobs

Découvrez les états des jobs et l’interrogation d’état

Exemples de code

Consultez des exemples complets avec gestion des webhooks