Webhooks en la sección “Avatares de vídeo”: notificación a tu servidor cuando el vídeo esté listo
Webhooks en la sección "Avatares de vídeo" es una forma de saber que el vídeo está listo, sin necesidad de actualizar manualmente la página: tan pronto como se completa el vídeo, se envía una solicitud POST a la dirección de su servidor, y su propio servidor decide qué hacer a continuación: escribir el enlace a la base de datos, enviar el archivo al cliente o comenzar el siguiente paso. La pestaña es necesaria para quienes hacen vídeos en lotes o integran la generación de avatares en su producto: en lugar de interminables comprobaciones de "listo o aún no", llega una breve notificación exactamente en el momento adecuado.
¿Por qué es esto necesario?
Renderizar un vídeo no es una operación instantánea y no tiene sentido esperarlo en una pestaña abierta. Según las mediciones de la plataforma del 07/09/2026, un vídeo Kling 3.0 de cinco segundos en 1080p se considera un promedio de 115 segundos, y en el 95% de los casos cabe en 165. Para Sora 2, la misma tarea toma un promedio de aproximadamente 145 segundos. Si verifica el estado cada pocos segundos, aparecerán docenas de solicitudes vacías en un video; El webhook aparece solo una vez: cuando el resultado realmente aparece.
El volumen también habla por sí solo. Según el registro de generación de la plataforma, durante 30 días (del 3 de septiembre al 2 de octubre de 2026), se iniciaron 3292 tareas de video, de las cuales 2369 se completaron con éxito. Los videos se cuentan en segundo plano y finalizan en diferentes momentos; esto no se puede rastrear manualmente y un manejador de notificaciones ordenado resuelve el problema por sí solo.
¿Qué hace la pestaña "Webhooks"?
Se trata de enviar notificaciones, sin magia. Usted registra una dirección, elige a qué eventos suscribirse y recibe un secreto de suscripción. La lista de puntos finales registrados se almacena allí mismo: puede ver la dirección, los eventos seleccionados, el estado y si el punto final tiene un secreto. El secreto se puede volver a publicar (el anterior dejará de funcionar inmediatamente) o el punto final se puede eliminar por completo.
El evento proviene únicamente de tus vídeos: el vídeo de otra persona no saldrá, aunque haya sido contado en el mismo momento. También hay un registro de eventos entregados: es conveniente verificar si algo realmente llegó a su servidor.
Cómo empezar: paso a paso
- Sección abierta "Avatares de vídeo" y panel de webhook en dirección directa /ru/avatars?tab=webhooks.
- Inicie sesión en su cuenta: la configuración no está disponible para invitados; al hacer clic, se abrirá una ventana de inicio de sesión.
- En el campo "Dirección del punto final", ingrese la dirección HTTPS pública de su servidor, por ejemplo https://example.com/avatar-webhook. HTTP no funcionará: la entrega y la firma están diseñadas para un canal seguro.
- Marque los eventos requeridos. Si no selecciona nada, quedará suscrito a todos los eventos a la vez.
- Haga clic en "Agregar punto final". Inmediatamente después de la creación, aparecerá el secreto de suscripción; cópielo y guárdelo: no se volverá a mostrar.
- Si aún no tiene su propio servidor, haga clic en "Sustituir nuestro receptor"; luego las notificaciones se acumularán en el registro de eventos entregados directamente en la pestaña.
Cómo asegurarse de que la solicitud sea nuestra y no falsa
Cada solicitud va acompañada de un encabezado de firma: este es HMAC-SHA256, calculado a partir del cuerpo sin formato de la solicitud como su secreto. Por tu parte, cuenta la misma firma y compara: si no coincide, descartamos la solicitud. Nuestro receptor hace exactamente esto y responde con 401 a una firma incorrecta. Mantenga el secreto en el servidor, en las variables de entorno y no en el código del cliente.
Lo que viene en la solicitud.
El cuerpo es JSON simple con el tipo de evento y los datos de la entidad. Por ejemplo, para un vídeo terminado, este es el evento BLK0 con el identificador de vídeo dentro. La lista completa de tipos de eventos disponibles se muestra en la pestaña: puede ordenarla y dejar solo lo que su servicio realmente necesita.
Cuánto cuesta
El registro de endpoints, la relanzación de secretos, la eliminación y el registro de eventos no cancelan los tokens: se trata de una configuración de notificación, no de una generación. Los tokens se gastan únicamente en el vídeo en sí: el precio en tokens es visible antes del lanzamiento y, si la tarea falla, se devuelve lo que se canceló. No hay suscripción: los nuevos usuarios reciben tokens iniciales para sus primeras pruebas.
Con que combinar
- "Tareas por lotes" — lanzar docenas de vídeos con una sola tarea; Un webhook eliminará la necesidad de un control de preparación manual.
- "Biblioteca multimedia" — almacenamiento de códigos fuente y archivos terminados.
- "Traducción de vídeo" Y "Corte de clips" — próximos pasos tras generación.
Preguntas frecuentes
¿Qué dirección es adecuada para un webhook?
Solo HTTPS público. No se aceptan direcciones locales ni HTTP: la notificación debe pasar por un canal seguro y su servidor debe ser accesible desde el exterior.
¿Es posible recibir notificaciones si no hay servidor?
Sí. Haga clic en "Sustituir nuestro receptor": los eventos se acumularán en el registro "Eventos entregados" de la pestaña y se podrán ver sin su backend.
¿Qué hacer si la firma no coincide?
Compruebe que está leyendo HMAC-SHA256 del cuerpo de la solicitud sin formato (y no del JSON analizado) y que está utilizando el secreto actual: después de volver a emitirlo, el anterior deja de funcionar inmediatamente.
¿Esto se paga?
La configuración de webhooks no cancela los tokens. Los tokens se gastan únicamente en la generación de vídeos; su precio es visible antes del lanzamiento; No hay suscripción, los nuevos usuarios reciben tokens iniciales.