Webhooks: Firma HMAC, Reentregas y Buenas Prácticas
Cómo recibir el resultado de las transcripciones por webhook: firma HMAC-SHA256, cabeceras X-VPT-Signature y X-VPT-Event, 6 intentos de reentrega con backoff.
En lugar de estar consultando la API para saber si la transcripción ha terminado, indicas un webhook_url en la petición y VoxScriber envía un POST a tu servidor cuando el trabajo finaliza, tanto si termina con éxito como si falla. Es la forma recomendada de integrarse: gastas menos peticiones y el resultado llega al momento.
Cómo funciona
- Envías el audio con un
webhook_url(obligatoriamentehttps). - Cuando termina el procesamiento, hacemos un POST a esa URL con el resultado.
- Tu servidor responde con un estado
2xxpara confirmar la recepción.
Cada entrega incluye dos cabeceras de identificación:
| Cabecera | Contenido |
|---|---|
X-VPT-Event | El tipo de evento (finalización, error, etc.) |
X-VPT-Signature | Firma HMAC-SHA256 de la entrega |
Valida siempre la firma antes de confiar en el contenido: calcula el HMAC-SHA256 del cuerpo recibido y compáralo con el valor de la cabecera X-VPT-Signature. Toda petición sin una firma válida debe descartarse: cualquiera podría descubrir la URL de tu endpoint.
Reentregas automáticas
Si tu endpoint está caído o tarda demasiado, lo intentamos de nuevo:
- Tiempo de espera por intento: 15 segundos.
- Máximo de intentos: 6.
- Espera entre intentos (backoff): 5 min → 30 min → 2 h → 6 h → 24 h.
Todas las entregas quedan persistidas en nuestro lado, así que es posible auditar el historial con el soporte si se pierde algo.
Responde al webhook inmediatamente con 200 y procesa el contenido de forma asíncrona (cola, job). Si tu procesamiento tarda más de 15 segundos, la entrega cuenta como fallo y entra en la cola de reentrega, por lo que podrías acabar recibiendo el mismo evento dos veces. Trata los eventos de forma idempotente.
Siempre recibes un desenlace
Los trabajos que se quedan bloqueados no desaparecen en silencio:
- Un trabajo en la cola parado durante más de 10 minutos se vuelve a encolar automáticamente.
- Un trabajo en procesamiento bloqueado durante más de 60 minutos se marca como fallido y dispara un webhook de error a tu URL.
Es decir, por cada audio enviado, tu sistema recibe un callback final, de éxito o de error.
FAQ
Mi servidor estuvo caído. ¿He perdido el resultado?
Probablemente no: hay hasta 6 intentos repartidos a lo largo de ~24 horas. Si todos fallan, el historial de entregas queda registrado; habla con el soporte para reprocesarlo.
¿Puedo usar una URL http (sin TLS)?
No. Por seguridad, solo aceptamos URLs https, sin redirecciones, y las direcciones internas/privadas están bloqueadas.
¿Cómo diferencio un webhook de éxito de uno de error?
Por la cabecera X-VPT-Event, que identifica el tipo de evento, y por el contenido del cuerpo de la entrega.
¿Qué tiene que responder mi endpoint?
Cualquier estado 2xx dentro de 15 segundos. Cualquier otro estado (o timeout) cuenta como fallo y genera una reentrega.
Artículos relacionados
¿No te ha quedado claro? Abre un ticket: nuestro equipo responde rápido.