Ontvang projectmeldingen

Bereid de ontvanger voor

Webhooks sturen HTTP als een video klaar is voor controle, export voltooit of een project mislukt of wordt geannuleerd. Beschikbaar bij Max-abonnementen.

Een openbare HTTPS-URL voor POST is nodig, uitsluitend poort 443. Localhost en privénetwerken ontvangen niet direct. CaptionBolt volgt geen redirects; gebruik een openbare HTTPS-tunnel voor lokaal testen.

Vervang https://receiver.example/captionbolt door uw URL.

Voeg een endpoint toe

1. Open Instellingen → Integraties.
2. Voer HTTPS-doel-URL in en kies gebeurtenissen.
3. Kies Webhook toevoegen.
4. Bewaar het ondertekeningsgeheim; het verschijnt één keer.

Dit verifieert meldingen en verschilt van uw API-sleutel.

Aanmaken via REST kan ook. Stel CAPTIONBOLT_API_KEY met webhooks:manage in volgens de API-gids:

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

Het antwoord bevat id en secret. Bewaar het geheim veilig in de ontvangeromgeving.

Kies gebeurtenissen

| Gebeurtenis | Betekenis | | --- | --- | | project.ready | Verwerking klaar; controle of export mogelijk | | project.completed | Export voltooid en resultaten beschikbaar; standaard geselecteerd | | project.failed | Verwerking of export mislukt; standaard geselecteerd | | project.cancelled | Project geannuleerd |

Gebeurtenissen omvatten geschikte videoprojecten van website, REST en MCP. Nieuwe endpoints ontvangen alleen toekomstige gebeurtenissen, geen eerdere wijzigingen. Zelfstandige Transcripts, verwijderde en verlopen projecten zijn uitgesloten.

project.ready betekent niet geëxporteerd of door een mens gecontroleerd.

{
  "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"
  }
}

Gebeurtenissen bevatten metadata, geen video of ondertiteltekst. data.resultUrl vereist REST-authenticatie. Vraag nieuwe links met projects:read op en download zonder sleutel. Zie downloads.

Controleer binnenkomende verzoeken

CaptionBolt gebruikt Standard Webhooks. Verifieer de handtekening op de exacte onbewerkte body voordat u parseert of handelt. Headers: webhook-id, webhook-timestamp, webhook-signature.

Voorbeeld van Node.js-ontvanger

Dit voorbeeld verifieert handtekeningen en logt ID en type voor testen. Het gebruikt Node.js 24; andere talen zijn mogelijk. Installeer de JavaScript-verifier in uw ontvangerproject:

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

Bewaar als 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");

Start node receiver.mjs en maak /captionbolt bereikbaar via HTTPS of tunnel. CaptionBolt gebruikt de openbare HTTPS-URL, niet het lokale adres.

De verifier controleert handtekening en tijd; houd de klok correct. Parseer en serialiseer JSON niet vóór verificatie. Log geen geheim of volledige body.

Vervang in productie logging door duurzame ontvangst: dedupliceer op id, sla gebeurtenis of taak op vóór 2xx en verwerk asynchroon. Geef bij opslagfouten een fout terug zodat opnieuw proberen mogelijk is. Dit voorbeeld test alleen ontvangst, zonder duurzame wachtrij of downloads.

Stuur een test

1. Start de ontvanger en stel het geheim in.
2. Open het endpoint in Instellingen → Integraties, kies Test verzenden.
3. Controleer Aflevergeschiedenis.
4. Bevestig een geverifieerde webhook.test in het log.

Eén actieve test per endpoint. Wacht op afronding en daarna minstens 60 seconden. Handmatige herhalingen hebben ook wachttijd; volg het teruggegeven interval.

Behandel webhook.test apart; het is geen voltooide video. Test resultaten met een toekomstige echte projectgebeurtenis.

Bij fouten controleert u URL, geheim, body en antwoord. Bevestig binnen 15 seconden. Niet-2xx, verbindingsfouten en ontbrekende bevestiging leiden tot herhaling.

Beheer herhalingen en geheimen

Meldingen kunnen dubbel of buiten volgorde komen. Dedupliceer op ID en lees zo nodig actuele projectstatus.

Drie automatische pogingen: eerst direct, ongeveer één minuut na de eerste fout, vijf minuten na de tweede. Daarna stopt automatische aflevering. Herstel en kies Opnieuw bezorgen: hetzelfde ID, drie nieuwe pogingen. Geschiedenis blijft 30 dagen.

Kies Geheim vernieuwen, bewaar het nieuwe geheim en werk de ontvanger bij. Het oude blijft 24 uur geldig; beide handtekeningen gaan in die periode mee. Verdere rotatie is tot het einde geblokkeerd.

Uitschakelen stopt openstaande afleveringen; een lopend verzoek kan eindigen. Verwijderen wist ook geschiedenis. Projectverwijdering of verlopen toegang stopt openstaande meldingen. Webhooks verlengen de 14 dagen niet; haal resultaten vooraf op en bewaar ze.