Recibir notificaciones de proyectos

Crear un destino

Cuando se abra el acceso, añada un receptor HTTPS público en Configuración → Integraciones, seleccione eventos y guarde el secreto de firma que se muestra una sola vez. También puede usar una clave con webhooks:manage:

curl --fail-with-body https://api.captionbolt.com/v1/webhooks \
  -H "Authorization: Bearer $CAPTIONBOLT_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://receiver.example/captionbolt","events":["project.completed","project.failed"]}'

Sustituya la URL por su receptor real. Solo se admite HTTPS público por el puerto 443, sin redirecciones. Localhost y las redes privadas no reciben entregas directamente.

Elegir eventos

project.completed: exportación terminada; seleccionado por defecto.
project.failed: fallo de procesamiento o exportación; seleccionado por defecto.
project.ready: procesamiento completo, listo para revisar o exportar.
project.cancelled: proyecto cancelado.

Incluye vídeos válidos de su cuenta creados en la aplicación, REST o MCP. Excluye Transcripts independientes, proyectos eliminados o fuera del plazo de acceso. Ready no confirma una revisión humana.

{
  "id": "event-uuid",
  "type": "project.completed",
  "createdAt": "2026-09-10T12:00:00.000Z",
  "data": {
    "projectId": "project-uuid",
    "status": "completed",
    "stage": "export",
    "resultUrl": "https://api.captionbolt.com/v1/projects/project-uuid/result"
  }
}

data.resultUrl es un endpoint autenticado, no el archivo de vídeo. Solicítelo con su API Key de lectura para obtener enlaces nuevos. Los eventos contienen metadatos, no vídeos ni subtítulos.

Verificar antes de procesar

Se utiliza Standard Webhooks. Use un verificador compatible o aplique estas comprobaciones:

Conserve el cuerpo original y lea webhook-id, webhook-timestamp y webhook-signature.
Quite whsec_ del secreto, decodifique base64 y calcule HMAC-SHA256 sobre id.timestamp.rawBody. Compare la firma base64 en tiempo constante.
Rechace fechas pasadas o futuras fuera de una tolerancia limitada, por ejemplo cinco minutos. Durante la rotación puede haber varias firmas v1, separadas por espacios; acepte una que coincida con una clave fiable.
Elimine duplicados por ID de evento y persista el trabajo antes de responder 2xx. Procese después de forma asíncrona y responda antes del límite de 15 segundos.

El secreto de firma es distinto de la API Key. Una rotación muestra el nuevo secreto una vez y permite 24 horas de solapamiento; no se puede volver a rotar durante ese periodo.

Probar y recuperar entregas

La prueba de configuración envía webhook.test; trátelo por separado. Consulte el historial de los últimos 30 días, corrija el receptor y reintente manualmente una entrega fallida o ya entregada.

Los eventos pueden repetirse o llegar desordenados. Las respuestas no 2xx, los fallos de conexión o la ausencia de confirmación permiten tres intentos automáticos en total: el inicial y otros dos tras aproximadamente uno y cinco minutos. El tercer fallo detiene la entrega automática. Un reintento manual mantiene el ID y reinicia los tres intentos; el receptor debe ser idempotente.

Desactivar detiene entregas pendientes, aunque una solicitud en curso puede terminar. Borrar el destino elimina su historial. Borrar o dejar caducar el proyecto detiene sus notificaciones pendientes. Los Webhooks no amplían el acceso al vídeo; guarde los resultados a tiempo o consulte el estado del proyecto.