Webhooks: entérate en cuanto tu vídeo esté listo

Generar vídeo lleva tiempo. Un clip de 5 a 10 segundos suele tardar entre unos minutos y un cuarto de hora; uno de 30 segundos, entre veinte y treinta minutos, y en horas de mucha demanda puede haber cola. Hasta ahora tenías que consultar el estado de la tarea cada pocos segundos: escribir el bucle, gestionar los tiempos de espera y recordar qué tareas seguían abiertas cuando tu servicio se reiniciaba.

Ya no. En cuanto una tarea termina, tanto si sale bien como si falla, enviamos el resultado directamente a tu servidor.

Dos formas de recibirlo

• URL predeterminada de la cuenta: en la consola, abre Configuración → Webhook, escribe la URL que recibirá los eventos y marca los que quieras. A partir de ahí, cada tarea de vídeo o imagen que envíes por la API te avisará cuando termine.
• Por petición: añade callback_url al enviar una tarea y el resultado de esa tarea irá solo a esa URL. Si sueles escribir callBackUrl, también funciona.

curl https://nezhagate.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.5", "prompt": "un barco de papel a la deriva por una calle lluviosa de noche", "duration": 5,
       "callback_url": "https://your-app.com/webhooks/nezhagate"}'

Para qué sirve

• Apps de vídeo, miniprogramas y sitios web: tu usuario puede cerrar la página justo después de enviar la tarea. Cuando el vídeo está listo, te llega la notificación: le mandas un mensaje en la app, un SMS o un correo, y añades el clip a su biblioteca.
• Imágenes en lote: envía de una vez cientos de fotos de producto o imágenes publicitarias, y cada una llega a tu biblioteca de medios o a tu CDN en cuanto está lista. Las que fallan quedan registradas aparte, para que retoques el prompt y las vuelvas a enviar.
• Bots de chat: alguien escribe un prompt en un grupo de Telegram, Discord, Lark o WeCom; tu bot responde «generando…» al instante y, cuando llega la notificación, publica el vídeo en el grupo.
• Funciones serverless: Vercel, Cloudflare Workers y las funciones en la nube no están pensados para bucles de consulta de media hora. La función puede terminar justo después de enviar la tarea; la notificación dispara el paso siguiente.
• Avisos de saldo bajo: recibe una sola notificación cuando tu saldo baje del número de créditos que hayas fijado. Redirígela al canal de Slack, Lark o DingTalk de tu equipo para que alguien recargue antes de que se agote, y no después de que tu servicio se pare en mitad de la noche.

¿Es fiable?

• Verificable: cada notificación va firmada con el esquema Standard Webhooks (el mismo que usan los webhooks de OpenAI). Hay bibliotecas listas para la mayoría de los lenguajes, y con unas pocas líneas de código confirmas que una notificación viene realmente de nosotros.
• Con reintentos automáticos: si tu servidor no responde con un 2xx en 10 segundos, volvemos a intentarlo tras 1 minuto, 5 minutos, 30 minutos, 2 horas y 6 horas. Todos los reintentos llevan el mismo ID de evento, así que descartar duplicados es fácil.
• Completa: la notificación lleva exactamente lo que devuelve el endpoint de la tarea, con la URL del vídeo y el consumo incluidos. Una tarea fallida ya se ha reembolsado íntegramente, y la notificación indica por qué falló.
• Con historial: la consola muestra los envíos recientes con el resultado de cada uno, los conserva 30 días y te permite reenviar cualquiera.

Configúralo en tres pasos

1. Prepara en tu servidor una URL que acepte peticiones POST. La documentación de webhooks incluye ejemplos completos de verificación de firmas en Python y Node.js.
2. En la consola, abre Configuración → Webhook, escribe la URL y haz clic en «Enviar evento de prueba» para comprobar que llega.
3. Envía tus tareas como siempre y espera la notificación. Para que el resultado de una tarea concreta vaya a otro sitio, añade callback_url a esa petición.