Skip to main content

​
Descripción general

En lugar de consultar GET /jobs/{id} repetidamente, puedes proporcionar una URL de webhook para recibir una solicitud POST cuando tu job se complete. Esto es más eficiente y reduce las llamadas innecesarias a la API.

​
Uso de webhooks

Agrega el encabezado X-Webhook-URL a cualquier solicitud de generación. Cuando el job alcance un estado terminal (completado, fallido o cancelado), la API enviará una solicitud POST a tu URL con los datos completos 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}`);
// Tu webhook recibirá los resultados cuando se complete

​
Payload del webhook

Cuando el job se completa, tu URL de webhook recibe una solicitud POST con los datos 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://..."]
  }
}

​
Mejores prácticas

Responde rápidamente — devuelve un código de estado 2xx de inmediato. Procesa los datos del webhook de forma asíncrona si es necesario.
Valida el payload — verifica que el job_id coincida con un job que hayas iniciado antes de procesar los resultados.
  • Usa endpoints HTTPS por seguridad
  • Implementa idempotencia por si hay entregas duplicadas
  • Registra la recepción de webhooks para depuración

​
Webhooks vs. sondeo

EnfoqueVentajasDesventajas
WebhooksNotificaciones en tiempo real, menos llamadas a la APIRequiere un endpoint público
SondeoFunciona en cualquier lugar, no requiere servidorMás llamadas a la API, ligera demora
Usa webhooks cuando tengas un servidor que pueda recibir solicitudes HTTP. Usa sondeo para aplicaciones del lado del cliente o cuando no puedas exponer un endpoint público.

​
Próximos pasos

Ciclo de vida de un job

Aprende sobre los estados de los jobs y el sondeo de estado

Ejemplos de código

Consulta ejemplos completos con manejo de webhooks