Skip to main content

​
Panoramica

Invece di effettuare polling su GET /jobs/{id} ripetutamente, puoi fornire un URL webhook per ricevere una richiesta POST quando il tuo job si completa. È più efficiente e riduce le chiamate API non necessarie.

​
Utilizzo dei webhook

Aggiungi l’intestazione X-Webhook-URL a qualsiasi richiesta di generazione. Quando il job raggiunge uno stato terminale (completato, fallito o cancellato), l’API invierà una richiesta POST al tuo URL con i dati completi del 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

​
Payload del webhook

Quando il job si completa, l’URL webhook riceve una richiesta POST con i dati del 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://..."]
  }
}

​
Buone pratiche

Rispondi rapidamente - Restituisci prontamente un codice di stato 2xx. Se necessario, elabora i dati del webhook in modo asincrono.
Valida il payload - Verifica che il job_id corrisponda a un job che hai avviato prima di elaborare i risultati.
  • Usa endpoint HTTPS per la sicurezza
  • Implementa l’idempotenza in caso di consegne duplicate
  • Registra le ricezioni dei webhook per il debug

​
Webhook vs Polling

ApproccioProContro
WebhookNotifiche in tempo reale, meno chiamate APIRichiede un endpoint pubblico
PollingFunziona ovunque, non richiede serverPiù chiamate API, lieve ritardo
Usa i webhook quando hai un server in grado di ricevere richieste HTTP. Usa il polling per applicazioni lato client o quando non puoi esporre un endpoint pubblico.

​
Prossimi passi

Ciclo di vita del job

Scopri gli stati dei job e il polling dello stato

Esempi di codice

Vedi esempi completi con gestione dei webhook