Añade webhook_url al crear el trabajo
Puedes enviarlo junto a un enlace de video, en la reserva de una subida por partes o como campo de un formulario multipart. No se puede combinar con reuse_recent. Consulta los parámetros del webhook.
Úsalo para tareas que continúan después del request inicial: procesar entrevistas, archivar episodios o transcribir una lista de videos. Guarda el ID de transcripción junto a tu propio registro para asociar el aviso con la acción del usuario.
Configura el endpoint HTTPS público definitivo. No seguimos redirecciones y localhost no es un destino válido. Revisamos la dirección al crear y al entregar el evento. El ejemplo usa un archivo para que puedas probar el flujo con una grabación propia.
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-F [email protected] \
-F webhook_url=https://example.com/hooks/transcript1Confirma el evento sin procesarlo todo en el request
data contiene el objeto de transcripción, sin el texto. Usa data.id y type para detectar duplicados. Cuando recibas transcription.completed, descarga la transcripción por su ID.
Un evento puede llegar más de una vez. Incluso si tu código ya lo procesó, reintentaremos si la respuesta tarda más de 10 segundos. Tras verificar la firma, guarda o encola el evento de forma duradera y responde 2xx cuanto antes. Registra la combinación de ID y tipo antes de publicar contenido o avisar a un usuario.
Descarga el texto en una tarea en segundo plano. Si recibes transcription.failed, revisa data.error y actualiza tu estado. Como las cancelaciones no envían avisos, el código que cancela también debe actualizar el estado de tu aplicación.
X-Transcript1-Signature: t=<unix seconds>,v1=<hex digest>
{
"type": "transcription.completed",
"created_at": "2026-10-13T09:30:04.000Z",
"data": {
"id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
"object": "transcription",
"status": "completed",
"transcript_source": "speech_to_text",
"billed_minutes": 4,
"error": null
}
}Cómo verificar la firma de un webhook HMAC-SHA256
Firma t seguido de un punto y del cuerpo original con HMAC-SHA256 y tu secreto whsec_. Compara las firmas en tiempo constante y rechaza marcas de tiempo demasiado alejadas de la actual. La guía de verificación incluye la validación completa.
Lee el cuerpo tal como llegó, antes de pasarlo por un parser JSON. Volver a serializarlo puede cambiar espacios u orden de claves y romper la firma. Valida el header y la marca de tiempo, compara firmas de la misma longitud y solo después interpreta el JSON. El fragmento de abajo asume que ya extrajiste y validaste t y v1.
La documentación incluye ejemplos completos de Node.js y Python con una tolerancia de 5 minutos. Usa el secreto completo, incluido whsec_. Si lo rotas, los envíos posteriores usan de inmediato la clave nueva.
const expected = crypto
.createHmac('sha256', secret)
.update(`${t}.${rawBody}`)
.digest('hex');
const valid = v1.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));Prueba los fallos y los duplicados antes de publicar
Prueba un evento de éxito, uno de fallo y un duplicado. La misma transcripción no debe publicarse dos veces; un fallo no debe activar una descarga seguida de publicación sin texto. Prueba por separado el rechazo de firmas y los errores de tu propio procesamiento.
Cada intento espera hasta 10 segundos. No retrases la confirmación mientras indexas texto o llamas a un modelo. Después de guardar el evento y responder, tu propia cola debe encargarse de reintentar esas tareas.
Ante errores de conexión, respuestas distintas de 2xx o falta de respuesta, esperamos 2, 4, 8, 16 y 32 minutos entre reintentos: son 6 intentos en total. No seguimos redirecciones. Registra el ID, el tipo de evento y lo ocurrido en la entrega, pero nunca el secreto de firma.
Si se agotan los intentos, consulta los IDs conocidos con el endpoint de lectura. Guarda esos IDs desde la creación: un webhook perdido no debería obligarte a enviar otra vez la grabación para saber qué ocurrió.