Webhooks: hendelser, payloads og signaturer

Med webhooks kan systemene dine reagere i det øyeblikket Inwista er ferdig med jobben: når en transkripsjon fullføres eller en videoeksport er rendret, POSTer Inwista en signert JSON-hendelse til et HTTPS-endepunkt du kontrollerer. Bruk det til publiseringspipelines, arkivsystemer, prosjektverktøy — alt som skal skje automatisk etter at Inwista er ferdig.

Oppsett og signeringshemmeligheten

Under My workspace → Integrations, koble til Webhooks-kortet og legg inn endepunkt-URL-en din (HTTPS kreves). Inwista genererer en signeringshemmelighet med prefikset whsec_ og viser den nøyaktig én gang — lagre den i hemmelighetshåndteringen din med det samme. Du kan rotere hemmeligheten når som helst fra integrasjonsinnstillingene; den gamle slutter å virke umiddelbart.

Bruk Send test event i innstillingene for å sende en signert webhook.test-hendelse til endepunktet og bekrefte oppsettet før reell trafikk. Endrer du endepunkt-URL-en senere, beholdes samme hemmelighet.

Hendelser

• transcript.completed Sendes én gang per prosjekt, når den første transkripsjonen er ferdig. Inneholder nedlastingslenker for transkripsjonsfilene i formatene som er konfigurert på integrasjonen.
• export.completed Sendes hver gang en videoeksport er ferdig rendret. Inneholder den renderte videoen pluss ferske transkripsjonsfiler som reflekterer eventuelle undertekstredigeringer gjort etter transkripsjonen.
• webhook.test Sendes manuelt fra integrasjonsinnstillingene, for å verifisere mottakeren din.

Begge hendelsestypene kan slås av og på uavhengig av hverandre i integrasjonsinnstillingene. Hendelser sendes ved hver abonnerte forekomst, uavhengig av lagringsvalg per eksport — webhooks er varsler, ikke leveringsdestinasjoner.

Payload

Alle hendelser deler samme konvolutt: en event-type, en unik id for deduplisering, et Unix-timestamp, workspaceId og en project-blokk. Filbærende hendelser har i tillegg en files-array; export.completed inkluderer også et video-objekt.

{
  "event": "export.completed",
  "id": "evt_9c1b7e2a4f0d4b6e8a12",
  "timestamp": 1784034017,
  "workspaceId": "UK6naH1L1sMtzTVcVZih",
  "project": {
    "id": "abc123def456",
    "name": "Intervju — Episode 12",
    "language": "no",
    "durationSeconds": 1834
  },
  "files": [
    {
      "format": "srt",
      "name": "Intervju — Episode 12.srt",
      "mimeType": "application/x-subrip",
      "url": "https://storage.googleapis.com/...signed...",
      "expiresAt": 1784120417
    }
  ],
  "video": {
    "name": "Intervju — Episode 12.mp4",
    "mimeType": "video/mp4",
    "sizeBytes": 812340221,
    "url": "https://storage.googleapis.com/...signed...",
    "expiresAt": 1784120417
  }
}

url-verdiene er signerte nedlastingslenker gyldige i 24 timer (Unix-tidsstempelet expiresAt sier nøyaktig når) — hent det du trenger med en gang i stedet for å lagre lenkene. transcript.completed har samme form, bare uten video-objektet.

Verifisere signaturer

Hver forespørsel har tre headere: X-Inwista-Event (hendelsestypen), X-Inwista-Delivery (hendelses-ID-en) og X-Inwista-Signature — en HMAC-SHA256 av den rå forespørselskroppen, beregnet med signeringshemmeligheten din. Beregn den på nytt og sammenlign før du stoler på innholdet; uten denne sjekken kan hvem som helst som oppdager endepunkt-URL-en din mate deg med falske hendelser.

const crypto = require("crypto");

function verifyInwistaSignature(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return (
    signatureHeader.length === expected.length &&
    crypto.timingSafeEqual(
      Buffer.from(signatureHeader),
      Buffer.from(expected),
    )
  );
}

// Express example — capture the raw body for verification:
// app.post("/inwista-hook", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verifyInwistaSignature(req.body, req.get("X-Inwista-Signature"), process.env.INWISTA_WEBHOOK_SECRET)) {
//     return res.status(401).end();
//   }
//   const event = JSON.parse(req.body);
//   res.status(200).end(); // acknowledge fast, process async
// });

Viktig: beregn HMAC-en over den rå forespørselskroppen, ikke en reserialisert versjon av den parsede JSON-en — forskjeller i nøkkelrekkefølge og mellomrom vil bryte sammenligningen.

Levering, nye forsøk og deduplisering

• Kvitter med 2xx Svar innen 10 sekunder. Gjør tung prosessering asynkront etter at du har kvittert — et tregt svar regnes som feil.
• Nye forsøk Mislykkede leveringer prøves på nytt inntil to ganger til (omtrent 10 og 30 sekunder senere). Svar i 4xx-området regnes som permanente og prøves ikke på nytt, med unntak av 408 og 429.
• Dedupliser på id Hvis serveren din mottar en forespørsel men svaret går tapt, kan et nytt forsøk levere samme hendelse to ganger. id-feltet er stabilt på tvers av forsøk — bruk det til å ignorere duplikater.
• Automatisk pause Etter 10 mislykkede leveringer på rad setter Inwista endepunktet på pause og viser hvorfor i integrasjonsinnstillingene, der du kan gjenoppta når mottakeren din er fikset. Siste leverings status og HTTP-kode er alltid synlige der.