Saltar al contenido principal

Descripción general

En lugar de consultar GET /jobs/{id} mediante sondeo, proporciona a Krea una URL de webhook. Krea envía el job a esa URL cuando finaliza.

Uso de webhooks

Agrega el encabezado X-Webhook-URL a cualquier solicitud de generación. Cuando el job se completa, falla o se cancela, Krea envía una solicitud POST a esa URL.

Payload del webhook

El cuerpo de la solicitud tiene la misma estructura que la respuesta de GET /jobs/{id}:

Verificación de firmas

Krea firma cada webhook con Ed25519. Verifica la firma antes de confiar en un payload y rechaza las solicitudes que no tengan firma. Krea firma el SHA-256 en hexadecimal en minúsculas del timestamp, la URL, los metadatos y el cuerpo sin procesar de la solicitud, unidos por saltos de línea:
Para verificar una solicitud:
  1. Comprueba que X-Krea-Webhook-Url coincida exactamente con la X-Webhook-URL que enviaste con el job.
  2. Comprueba que el timestamp esté dentro de un margen de 5 minutos respecto a la hora actual de tu servidor.
  3. Acepta la solicitud si la firma se verifica con cualquier clave de https://api.krea.ai/.well-known/jwks.json. Almacena las claves en caché durante 24 horas como máximo. Krea publica una nueva clave 24 horas antes de empezar a firmar con ella.
Calcula el hash de los bytes sin procesar del cuerpo, no de un JSON serializado de nuevo. Por ejemplo, usa express.raw() en Express, await request.arrayBuffer() en frameworks basados en la Fetch API o request.get_data() en Flask. Si falta el encabezado X-Krea-Webhook-Metadata, trátalo como una cadena vacía.

Entrega y reintentos

Devuelve un 2xx en un plazo de 15 segundos. Si la solicitud agota el tiempo de espera, no puede conectarse o recibe un 5xx, 408, 423, 425 o 429, Krea reintenta durante unos 10 minutos, con un nuevo timestamp y una nueva firma en cada intento. Krea no reintenta ningún otro 4xx. El mismo job puede llegar más de una vez, así que elimina duplicados según job_id y status.

Webhooks vs. sondeo

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

Genera una imagen con la API, de principio a fin