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.

Payload del webhook

Cuando el job se completa, tu URL de webhook recibe una solicitud POST con los datos del job:

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

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