Webhookit: tapahtumat, payloadit ja allekirjoitukset

Webhookien avulla omat järjestelmäsi voivat reagoida sillä hetkellä, kun Inwista saa työn valmiiksi: kun transkriptio valmistuu tai videovienti on renderöity, Inwista POSTaa allekirjoitetun JSON-tapahtuman hallitsemaasi HTTPS-päätepisteeseen. Käytä sitä julkaisuputkiin, arkistojärjestelmiin, projektityökaluihin — kaikkeen, minkä pitää tapahtua automaattisesti Inwistan valmistuttua.

Käyttöönotto ja allekirjoitussalaisuus

Kohdassa My workspace → Integrations, yhdistä Webhooks-kortti ja syötä päätepisteesi URL (HTTPS vaaditaan). Inwista generoi allekirjoitussalaisuuden etuliitteellä whsec_ ja näyttää sen tasan kerran — tallenna se salaisuuksienhallintaasi heti. Voit kierrättää salaisuuden milloin tahansa integraatioasetuksista; vanha lakkaa toimimasta välittömästi.

Käytä asetusten Send test event -painiketta lähettääksesi allekirjoitetun webhook.test-tapahtuman päätepisteeseesi ja varmistaaksesi kytkennän ennen oikeaa liikennettä. Päätepisteen URL:n vaihtaminen myöhemmin säilyttää saman salaisuuden.

Tapahtumat

• transcript.completed Lähetetään kerran per projekti, kun ensimmäinen transkriptio valmistuu. Sisältää latauslinkit transkriptiotiedostoihin integraatiossa määritetyissä muodoissa.
• export.completed Lähetetään joka kerta, kun videovienti valmistuu. Sisältää renderöidyn videon sekä tuoreet transkriptiotiedostot, jotka heijastavat transkription jälkeen tehtyjä tekstitysmuokkauksia.
• webhook.test Lähetetään manuaalisesti integraatioasetuksista vastaanottajasi varmistamiseksi.

Molemmat tapahtumatyypit voi kytkeä päälle ja pois toisistaan riippumatta integraatioasetuksissa. Tapahtumat lähetetään jokaisesta tilatusta esiintymästä riippumatta vientikohtaisista tallennusvalinnoista — webhookit ovat ilmoituksia, eivät toimituskohteita.

Payload

Kaikki tapahtumat jakavat saman kuoren: event-tyyppi, yksilöllinen id deduplikointiin, Unix-timestamp, workspaceId ja project-lohko. Tiedostoja kantavissa tapahtumissa on lisäksi files-taulukko; export.completed sisältää myös video-objektin.

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

url-arvot ovat allekirjoitettuja latauslinkkejä, jotka ovat voimassa 24 tuntia (Unix-aikaleima expiresAt kertoo tarkalleen milloin) — nouda tarvitsemasi heti sen sijaan, että tallentaisit linkit. transcript.completed on samanmuotoinen, vain ilman video-objektia.

Allekirjoitusten varmentaminen

Jokaisessa pyynnössä on kolme headeria: X-Inwista-Event (tapahtumatyyppi), X-Inwista-Delivery (tapahtuman ID) ja X-Inwista-Signature — HMAC-SHA256 raa'asta pyyntörungosta, laskettuna allekirjoitussalaisuudellasi. Laske se uudelleen ja vertaa ennen kuin luotat sisältöön; ilman tätä tarkistusta kuka tahansa päätepisteesi URL:n löytävä voi syöttää sinulle valetapahtumia.

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
// });

Tärkeää: laske HMAC raa'asta pyyntörungosta, ei jäsennetyn JSON:n uudelleensarjoitetusta versiosta — erot avainten järjestyksessä ja välilyönneissä rikkovat vertailun.

Toimitus, uudelleenyritykset ja deduplikointi

• Kuittaa 2xx:llä Vastaa 10 sekunnin sisällä. Tee raskas käsittely asynkronisesti kuittauksen jälkeen — hidas vastaus lasketaan epäonnistumiseksi.
• Uudelleenyritykset Epäonnistuneita toimituksia yritetään uudelleen enintään kaksi kertaa lisää (noin 10 ja 30 sekuntia myöhemmin). 4xx-alueen vastaukset käsitellään pysyvinä eikä niitä yritetä uudelleen, poikkeuksina 408 ja 429.
• Deduplikoi id:llä Jos palvelimesi vastaanottaa pyynnön mutta vastaus katoaa, uudelleenyritys voi toimittaa saman tapahtuman kahdesti. id-kenttä pysyy samana yritysten välillä — käytä sitä kaksoiskappaleiden ohittamiseen.
• Automaattinen tauko Kymmenen peräkkäisen epäonnistuneen toimituksen jälkeen Inwista keskeyttää päätepisteen ja näyttää syyn integraatioasetuksissa, joista voit jatkaa, kun vastaanottajasi on korjattu. Viimeisimmän toimituksen tila ja HTTP-koodi näkyvät siellä aina.