Descripción general
En lugar de consultarGET /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 encabezadoX-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 deGET /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:
- Comprueba que
X-Krea-Webhook-Urlcoincida exactamente con laX-Webhook-URLque enviaste con el job. - Comprueba que el timestamp esté dentro de un margen de 5 minutos respecto a la hora actual de tu servidor.
- 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.
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 un2xx 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