Recibe notificaciones de proyectos

Prepare el receptor

Los Webhooks envían solicitudes HTTP cuando un video está listo para revisar, termina la exportación, falla o se cancela. Las integraciones están disponibles con las suscripciones Max.

Necesita una URL HTTPS pública que acepte POST, exclusivamente en el puerto 443. Localhost y las redes privadas no reciben directamente; no se siguen redirecciones. Para pruebas locales, use un túnel HTTPS público.

Sustituya https://receiver.example/captionbolt por su URL real.

Añada un endpoint

1. Abra Configuración → Integraciones.
2. Introduzca URL HTTPS de destino y elija eventos.
3. Seleccione Añadir Webhook.
4. Guarde el secreto de firma; solo se muestra una vez.

El receptor verifica las notificaciones con este secreto, distinto de la clave API.

También puede crear el endpoint mediante REST. Configure CAPTIONBOLT_API_KEY con webhooks:manage según la guía API:

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"]}'

La respuesta devuelve id y secret. Guarde el secreto de forma segura en el entorno del receptor.

Elija eventos

| Evento | Significado | | --- | --- | | project.ready | Procesamiento terminado; puede revisar o exportar | | project.completed | Exportación terminada y resultados disponibles; seleccionado por defecto | | project.failed | Fallo del procesamiento o exportación; seleccionado por defecto | | project.cancelled | Proyecto cancelado |

Incluye proyectos de video compatibles de la cuenta, creados en la web, REST o MCP. Un endpoint nuevo recibe eventos futuros, no cambios anteriores. Excluye Transcripts independientes y proyectos borrados o fuera del plazo de acceso.

project.ready no significa exportado ni revisado por una persona.

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

Los eventos incluyen metadatos, no videos ni texto de subtítulos. data.resultUrl requiere autenticación REST. Use una clave con projects:read para obtener enlaces nuevos y descargue sin enviar la clave. Consulte descargas.

Verifique las solicitudes

CaptionBolt usa Standard Webhooks. Verifique la firma sobre el cuerpo original exacto antes de analizarlo o actuar. Las cabeceras son webhook-id, webhook-timestamp y webhook-signature.

Ejemplo de receptor Node.js

Este receptor mínimo verifica firmas y registra ID y tipo para probar la entrega. El ejemplo usa Node.js 24; puede usar otro lenguaje. Instale el verificador JavaScript en su propio proyecto receptor:

npm install standardwebhooks
read -r -s -p 'CaptionBolt signing secret: ' CAPTIONBOLT_WEBHOOK_SECRET
export CAPTIONBOLT_WEBHOOK_SECRET
printf '\n'

Guarde como receiver.mjs:

import { createServer } from "node:http";
import { Webhook } from "standardwebhooks";

const secret = process.env.CAPTIONBOLT_WEBHOOK_SECRET;
if (!secret) throw new Error("Set CAPTIONBOLT_WEBHOOK_SECRET.");
const verifier = new Webhook(secret);

createServer(async (request, response) => {
  if (request.method !== "POST" || request.url !== "/captionbolt") {
    response.writeHead(404).end();
    return;
  }
  let event;
  try {
    const chunks = [];
    let size = 0;
    for await (const chunk of request) {
      size += chunk.length;
      if (size > 65536) {
        response.writeHead(413).end();
        return;
      }
      chunks.push(chunk);
    }
    const rawBody = Buffer.concat(chunks).toString("utf8");
    event = verifier.verify(rawBody, {
      "webhook-id": request.headers["webhook-id"],
      "webhook-timestamp": request.headers["webhook-timestamp"],
      "webhook-signature": request.headers["webhook-signature"],
    });
  } catch {
    response.writeHead(400).end("Invalid webhook");
    return;
  }
  console.log("Verified event:", event.id, event.type);
  response.writeHead(204).end();
}).listen(3000, "127.0.0.1");

Ejecute node receiver.mjs y exponga /captionbolt mediante HTTPS o un túnel público. CaptionBolt debe acceder a la URL HTTPS pública, no a la dirección local.

El verificador comprueba firma y fecha; mantenga el reloj correcto. No analice y vuelva a serializar el JSON antes de verificar, ni registre el secreto o cuerpo completo.

En producción, sustituya el registro por recepción persistente: deduplique por id, guarde el evento o tarea antes de responder 2xx y procese de forma asíncrona. Si falla la persistencia, devuelva un error para permitir reintentos. El ejemplo solo prueba recepción; no implementa cola persistente ni descarga resultados.

Envíe una prueba

1. Inicie el receptor y configure el secreto.
2. Abra el endpoint en Configuración → Integraciones y elija Enviar prueba.
3. Compruebe Historial de entregas.
4. Confirme que se registró un webhook.test verificado.

Solo puede haber una prueba activa por endpoint. Espere a que termine y después al menos 60 segundos antes de otra. Los reintentos manuales también tienen una espera mínima; respete el intervalo devuelto.

Trate webhook.test aparte: no representa un video terminado. Use un evento real futuro para probar la obtención del resultado.

Si falla, revise URL, secreto, cuerpo original y respuesta. Confirme en 15 segundos. Respuestas no 2xx, errores de conexión o ausencia de confirmación provocan reintentos.

Gestione reintentos y secretos

Las notificaciones pueden repetirse o llegar desordenadas. Deduplique por ID y consulte el estado actual cuando necesite información reciente.

Hay tres intentos automáticos: el inicial, aproximadamente un minuto tras el primer fallo y cinco minutos tras el segundo. Después se detiene la entrega automática. Corrija el receptor y use Reintentar entrega; conserva el ID y abre otros tres intentos. El historial dura 30 días.

Use Rotar secreto, guarde el nuevo secreto y actualice el receptor. El antiguo vale 24 horas; durante ese plazo se incluyen ambas firmas. No se permite otra rotación hasta finalizar el solapamiento.

Desactivar detiene entregas pendientes; una solicitud en curso puede terminar. Borrar el endpoint elimina su historial. Borrar o caducar el proyecto detiene sus notificaciones pendientes. Los Webhooks no amplían los 14 días de acceso; obtenga y guarde los resultados antes.