> ## Documentation Index
> Fetch the complete documentation index at: https://www.krea.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Configurez des webhooks pour recevoir en temps réel les événements de fin de job, réduire le polling et créer des workflows asynchrones fiables dans votre application.

## 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.

<CodeGroup>
  ```javascript Node.js theme={null}
  // 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
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.krea.ai/generate/image/bfl/flux-1-dev \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -H "X-Webhook-URL: https://your-server.com/webhook" \
    -d '{
      "prompt": "a serene mountain landscape at sunset",
      "width": 1024,
      "height": 576
    }'
  ```

  ```python Python theme={null}
  import requests

  API_BASE = "https://api.krea.ai"
  API_TOKEN = "your-token-secret"

  response = requests.post(
      f"{API_BASE}/generate/image/bfl/flux-1-dev",
      headers={
          "Authorization": f"Bearer {API_TOKEN}",
          "Content-Type": "application/json",
          "X-Webhook-URL": "https://your-server.com/webhook"
      },
      json={
          "prompt": "a serene mountain landscape at sunset",
          "width": 1024,
          "height": 576
      }
  )

  job = response.json()
  print(f"Job ID: {job['job_id']}")
  # Your webhook will receive the results when complete
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      apiBase := "https://api.krea.ai"
      apiToken := "your-token-secret"

      payload := map[string]interface{}{
          "prompt": "a serene mountain landscape at sunset",
          "width":  1024,
          "height": 576,
      }

      jsonData, _ := json.Marshal(payload)
      req, _ := http.NewRequest("POST", apiBase+"/generate/image/bfl/flux-1-dev", bytes.NewBuffer(jsonData))
      req.Header.Set("Authorization", "Bearer "+apiToken)
      req.Header.Set("Content-Type", "application/json")
      req.Header.Set("X-Webhook-URL", "https://your-server.com/webhook")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      var job map[string]interface{}
      json.NewDecoder(resp.Body).Decode(&job)
      fmt.Printf("Job ID: %s\n", job["job_id"])
      // Your webhook will receive the results when complete
  }
  ```
</CodeGroup>

## 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 :

```json theme={null}
{
  "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

<Check>
  **Répondez rapidement** — Retournez rapidement un code de statut 2xx. Traitez les données du webhook de manière asynchrone si nécessaire.
</Check>

<Warning>
  **Validez la charge utile** — Vérifiez que le `job_id` correspond à un job que vous avez initié avant de traiter les résultats.
</Warning>

* 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

| Approche     | Avantages                                       | Inconvénients                            |
| ------------ | ----------------------------------------------- | ---------------------------------------- |
| **Webhooks** | Notifications en temps réel, moins d'appels API | Nécessite un point de terminaison public |
| **Polling**  | Fonctionne partout, aucun serveur nécessaire    | Plus 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

<CardGroup cols={2}>
  <Card title="Cycle de vie des jobs" icon="cube" href="/developers/job-lifecycle">
    Découvrez les états des jobs et l'interrogation d'état
  </Card>

  <Card title="Exemples de code" icon="code" href="/developers/examples/text-to-image">
    Consultez des exemples complets avec gestion des webhooks
  </Card>
</CardGroup>