Litterointi Make.comissa: webhook-first-putki

Litterointityö vie valmistuakseen minuutteja. Make-skenaario laskutetaan moduulin suorituksen perusteella. Nämä kaksi tosiasiaa vetävät eri suuntiin, ja juuri tuon jännitteen ratkaiseminen on se, mistä tässä oppaassa oikeasti on kyse.

Ilmeisin ratkaisu — lähetä tiedosto ja sitten odota, tarkista, odota, tarkista kunnes se on valmis — ei maksa mitään itse ylläpitämälläsi palvelimella. Makessa se ei ole ilmaista. Jokainen odotus ja jokainen tilan tarkistus on operaatio, ja neljän minuutin työ voi polttaa niitä kolmekymmentä pelkkään kysymykseen ”joko se on valmis?”.

Rakennamme sen siksi toisin päin. Inwista kertoo Makelle heti kun työ on valmis, ja viestin vastaanottava skenaario on kolme moduulia pitkä.

Lopuksi sinulla on:

Vastaanottoskenaario, joka herää kun litterointi on valmis
Lähetysskenaario, joka luovuttaa tiedostot Inwistalle ja pysähtyy sitten
Allekirjoituksen varmennus, jotta vastaanotin luottaa vain aitoihin tapahtumiin
Valinnaisia lisiä — käännösten rinnakkaisajo, kaksoiskappaleiden karsinta ja säilytysajan siivousajo

Kaikki pyörii julkisen Inwista API v1 -rajapinnan päällä Maken vakio-HTTP-moduulin kautta. Ei omaa sovellusta, ei koodia.

Ennen kuin aloitat

Tarvitset kolme asiaa:

Make-tilin — ilmaispaketti riittää tämän rakentamiseen, joskin sen operaatiokatto jää tuotantokäyttöön niukaksi
Inwistan API-avaimen — luo sellainen kohdassa Oma työtila → API-avaimet. Se alkaa merkeillä inw_live_
Mediaa, johon rajapinta ylettyy — rajapinta odottaa julkista https-osoitetta, joten Dropboxissa, Google Drivessa, S3:ssa tai omassa julkaisujärjestelmässäsi olevat tiedostot tarvitsevat jaettavan tai allekirjoitetun linkin

Sinun ei tarvitse ylläpitää webhook-päätepistettä missään. Make antaa sinulle osoitteen.

Huomio kustannuksista ennen kuin rakennat jotain, joka pyörii ilman valvontaa: litterointi laskutetaan 4 krediittiä alkavalta mediaminuutilta, ja veloitus tapahtuu kun työ otetaan vastaan. Epäonnistuneet työt hyvitetään automaattisesti. Suuntaa skenaario ensin pariin lyhyeen testitiedostoon, ennen kuin päästät sen arkistosi kimppuun.

Miksi rakenne ratkaisee tässä

Molemmat ratkaisut toimivat. Ne vain maksavat hyvin eri verran, ja Makessa tuo ero kertautuu joka kuukausi.

Pollaukseen perustuva skenaario työlle, joka valmistuu noin neljässä minuutissa ja jota tarkistetaan kahdenkymmenen sekunnin välein, näyttää suunnilleen tältä: yksi lähetys, sitten kaksitoista kierrosta odotusta plus tilan tarkistus plus reititin, ja lopuksi haku ja toimitus. Laske sen olevan 39 operaatiota tiedostoa kohden.

Webhook-versio jakautuu kahteen skenaarioon. Lähettäjä on liipaisin ja yksi HTTP-kutsu. Vastaanotin on webhook, jäsennys, haku ja toimitus. Laske sen olevan 6 operaatiota tiedostoa kohden.

Kahdellasadalla tallenteella kuukaudessa se tekee 7 800 operaatiota vastaan 1 200 — eron tilaustason noston ja pyöristysvirheen välillä. Se poistaa myös ne kaksi vikatilaa, jotka purevat pollaavia skenaarioita tuotannossa: suorituksen, joka venyy niin pitkäksi että se törmää Maken 40 minuutin kattoon, ja jumiin jääneen työn, joka pyörii hiljaa koko yön.

Rakenna ensin vastaanotin. Se on se osa, jonka on oltava oikein.

Vaihe 1: luo vastaanotin

Uusi skenaario. Lisää moduuli, valitse Webhooks → Custom webhook, napsauta Add, anna sille nimeksi vaikka inwista-transcripts ja kopioi osoite, jonka Make antaa.

Ennen kuin poistut ikkunasta, avaa webhookin lisäasetukset ja kytke päälle JSON pass-through.

Tämä on se asetus, jonka kaikki ohittavat, ja se kannattaa ymmärtää eikä vain kopioida. Inwista allekirjoittaa jokaisen toimituksen HMAC-tiivisteellä, joka lasketaan pyynnön rungon raakatavuista. Jos Make jäsentää JSON:n puolestasi, juuri nuo tavut ovat poissa — mukaan lukien avainten järjestys ja välilyönnit — etkä pysty enää toisintamaan allekirjoitusta. Pass-through antaa sinulle rungon koskemattomana yhtenä merkkijonona: se maksaa sinulle myöhemmin yhden ylimääräisen moduulin jäsennystä varten ja tuo sinulle ylipäätään mahdollisuuden varmentaa mitään.

Liitä nyt tuo osoite Inwistaan kohtaan Oma työtila → Integraatiot, tilaa sille tapahtuma transcript.completed ja kopioi näkyviin tuleva allekirjoitussalaisuus.

Vaihe 2: varmenna allekirjoitus

Napsauta hiiren oikealla painikkeella webhookista lähtevää yhteyttä ja lisää suodatin. Maken funktio sha256() laskee HMAC-tiivisteen heti kun annat sille avaimen, joten koko tarkistus mahtuu yhteen lausekkeeseen — ei salausmoduulia, ei koodia.

Ehto, Text: Equal to:

{{1.headers.x-inwista-signature}}

sha256={{sha256(1.data; "hex"; "your_signing_secret")}}

Kaksi yksityiskohtaa, jotka muuten vievät sinulta iltapäivän. Make tarjoaa saapuvien otsakkeiden nimet pienaakkosin, joten se on x-inwista-signature eikä se isoilla kirjaimilla kirjoitettu muoto, jonka näet dokumentaatiossamme. Ja otsakkeen arvossa on etuliite sha256=, joten joko lisää se eteen kuten yllä tai riisu se pois ennen vertailua.

Kaikki, mikä ei läpäise suodatinta, yksinkertaisesti pysähtyy. Allekirjoittamaton pyyntö ei koskaan yllä työtä tekeviin moduuleihin.

Lisää suodattimen jälkeen JSON → Parse JSON -moduuli, joka osoittaa kohteeseen 1.data. Tästä eteenpäin hyötykuorma käyttäytyy kuin mikä tahansa muu Maken bundle.

Vaihe 3: hae ja toimita

Tapahtuma sisältää jo kaiken tarvitsemasi:

{
  "event": "transcript.completed",
  "id": "evt_...",
  "timestamp": 1786902819,
  "workspaceId": "...",
  "project": {
    "id": "...",
    "name": "board-meeting-august.mp4",
    "language": "en",
    "durationSeconds": 3184
  },
  "files": [
    { "format": "srt", "name": "board-meeting-august.srt", "url": "https://...", "expiresAt": 1786989219 }
  ]
}

Lisää HTTP → Get a file ja mappaa osoite kenttään {{2.files[1].url}}.

Tuo [1] ei ole kirjoitusvirhe. Maken taulukot alkavat ykkösestä, ja jos tottumuksesta kurotat kohtaan [0], saat tyhjän arvon etkä virhettä — ja se matkaa sitten hiljaa eteenpäin ja ilmestyy kolmen päivän päästä nollatavuisena tiedostona Driveen.

Nuo osoitteet on allekirjoitettu ja ne ovat voimassa 24 tuntia. Hae tiedosto; älä tallenna linkkiä.

Kiinnitä perään se, mitä ”valmis” tiimillesi tarkoittaa — Google Drive, Dropbox, S3, Slack, HTTP-kutsu julkaisujärjestelmääsi, rivi Airtableen tai Notioniin.

Kolme moduulia ja suodatin. Siinä on koko vastaanotin, ja se käsittelee jokaisen työtilassa valmistuneen työn — myös ne tallenteet, jotka kollegasi lataavat käsin hallintapaneelin kautta ja joista mikään pollaava skenaario ei olisi koskaan saanut tietää.

Vaihe 4: lähettäjä

Toinen skenaario. Aloita siitä tapahtumasta, joka tarkoittaa ”jotain uutta on tullut”: Google Driven tai Dropboxin valvontamoduuli, Custom webhook omasta julkaisujärjestelmästäsi tai ajastettu kysely tietokantaan. Testatessasi aja se vain käsin.

Sen ainoa tehtävä on tuottaa julkisesti saavutettava osoite. Lisää HTTP → Make a request:

URL — https://api.inwista.ai/v1/transcriptions
Metodi — POST
Otsakkeet — Authorization: Bearer inw_live_your_key_here
Otsakkeet — Idempotency-Key: {{md5(1.fileUrl)}}
Rungon tyyppi — Raw, sisältötyyppi JSON

{
  "source_url": "{{1.fileUrl}}",
  "language": "en",
  "diarization": true,
  "metadata": { "source": "make", "scenario": "{{1.folderName}}" }
}

Kolme kenttää, jotka kannattaa ymmärtää:

language on se kieli, jota tiedostossa puhutaan, ei se kieli, jonka haluat ulos. Lähdekielellä litterointi tuottaa tarkat aikaleimat ja siistin tekstin; käännös tulee vasta sen jälkeen, valmiin litteroinnin päälle. Jos putkesi käsittelee useita kieliä, mappaa liipaisimen kansio tähän kenttään.

diarization kytkee päälle puhujamerkinnät. Jätä se pois yhden puhujan sisällöstä — se lisää käsittelyaikaa, jota et tarvitse.

metadata on sinun. Enintään 1 kt mitä tahansa, palautettuna sanatarkasti jokaisella luvulla ja webhookissa — juuri näin vastaanotin tietää, mihin skenaarioon, kurssiin tai tapaukseen tiedosto kuuluu ilman että mitään tarvitsee hakea erikseen.

Huomaa, mistä idempotenssiavain johdetaan. Suorituksesta johdettuna se suojaa sinua kyseisen yhden moduulin uudelleenyritykseltä. Tiedostosta johdettuna, kuten yllä, se suojaa sinua lisäksi siltä, että sama tallenne lähetetään kahdesti kahdesta eri ajosta — joka on ylivoimaisesti yleisin tapa maksaa vahingossa kahteen kertaan.

Vastaus palaa välittömästi tiedoilla status: "processing" ja id. Skenaario päättyy siihen. Se on suunnitelma toimimassa, ei suunnitelma epäonnistumassa.

Käännösten rinnakkaisajo Iteratorilla

Yksi tallenne kuudeksi kieleksi — juuri siinä Maken taulukkokäsittely maksaa itsensä takaisin.

Lisää vastaanottimeen litteroinnin saavuttua Tools → Set variable, jossa on kohdekieliesi lista, sitten sen yli kulkeva Iterator ja lopuksi yksi ainoa HTTP-moduuli silmukan sisään:

POST https://api.inwista.ai/v1/transcriptions/{{2.project.id}}/translate

{ "target_language": "{{4.value}}" }

Jokainen kutsu palauttaa 202 Accepted. Käännös ajetaan valmiin litteroinnin päälle, joten ajoitukset ovat jo oikein ja vain teksti muuttuu. Kuusi kieltä maksaa kuusi operaatiota, ja valmiit tiedostot saapuvat saman webhookin kautta, jonka jo rakensit.

Kun haet ne, pyydä niitä nimenomaisesti:

GET /v1/transcriptions/{id}/captions?format=srt&language=no

Kieliparametri on tiukka. Sellaisen kielen pyytäminen, jolta ei ole valmista käännöstä, palauttaa nimenomaisen virheen sen sijaan että antaisi hiljaa lähdekielen — juuri sitä sinä haluat putkessa, jota kukaan ei valvo.

Broadcast-tason tekstitykset

Raaka litterointi on sanatarkkaa. Tekstittäminen on käsityötä: rivien pituudet, lukunopeus, se kohta jossa lause katkeaa kahdelle ruudulle.

Yksi HTTP-moduuli lisää, POST /v1/transcriptions/{id}/enhance, ajaa litteroinnin tuon käsittelyn läpi — tekstin tiivistys, rivinvaihtojen tasapainotus, dialogin muotoilu ja lohkojen kestojen valvonta:

{
  "settings": {
    "maxLinesPerBlock": "2",
    "maxCharactersPerLine": 42,
    "textCondensation": "smart",
    "speakerDialogueFormat": "hyphens",
    "gapBetweenBlocks": "broadcasting"
  }
}

Sen jälkeen tekstityspäätepisteet tarjoilevat parannellun version automaattisesti. Mikään ei muutu ketjun loppupäässä.

Kun jokin menee pieleen: Maken virhereitit

Napsauta hiiren oikealla painikkeella mitä tahansa moduulia ja valitse Add error handler. Make antaa sinulle direktiivejä, joita tavallinen IF-haara ei pysty ilmaisemaan:

Break — pysäköi suorituksen kohtaan Incomplete Executions, jotta voit korjata syyn ja ajaa juuri sen bundlen uudelleen. Laita tämä lähetysmoduuliin.
Ignore — kirjaa virheen ja jatkaa. Sopii toimitusvaiheeseen, joka on mukava mutta ei välttämätön.
Resume — korvaa varasyötteellä ja jatkaa.
Rollback — peruu vahvistetun työn transaktionaalisissa moduuleissa.

Jokainen Inwistan virhe palauttaa saman rakenteen:

{ "error": { "code": "insufficient_credits", "message": "..." } }

Haaraudu kentän code perusteella, älä koskaan viestin tekstin. Koodeja vain lisätään version v1 sisällä eikä niitä koskaan nimetä uudelleen; viestit sen sijaan voidaan muotoilla uusiksi milloin tahansa.

Meidän puolellamme webhook-toimitus yritetään uudelleen kolme kertaa, ja jatkuvasti epäonnistuva päätepiste poistetaan käytöstä automaattisesti, syy näkyvissä integraatioasetuksissasi — rikkinäinen vastaanotin näyttäytyy siis tilana, jonka voit nähdä, eikä tapahtumina jotka katoavat äänettömästi.

Älä litteroi samaa tiedostoa kahdesti

Valvottujen kansioiden liipaisimet laukeavat uudelleen. Tiedostoja nimetään uudelleen. Joku lataa saman uudestaan.

Makessa on tähän oma vastaus: Data store. Luo sellainen lähdetiedoston tunnisteella avainnettuna, ja lisää lähettäjään ennen HTTP-kutsua Data store → Get a record, suodata sen perusteella ettei tietuetta ole, ja laita Add a record onnistuneen lähetyksen perään.

Kaksi operaatiota siihen, ettei kaksoislitteroinnista tarvitse maksaa. Idempotenssiavain kattaa yhden moduulin uudelleenyritykset; data store kattaa kaiken muun.

Arkaluontoiset tallenteet

Jos putkesi käsittelee aineistoa, jota mieluummin et haluaisi meidän säilyttävän — potilashaastatteluja, oikeudellisia tallenteita, sisäisiä henkilöstötilaisuuksia — lisää lähetykseen yksi kenttä:

{
  "source_url": "{{1.fileUrl}}",
  "language": "en",
  "retention": "none"
}

Asetuksella retention: "none" lähdemedia poistetaan heti kun litterointi valmistuu. Litterointi, tekstitykset, käännökset ja myöhemmät parannukset toimivat edelleen — vain ääni ja kuva ovat poissa. Lisäksi on store_media: false, joka säilyttää tiedoston käsittelyä varten mutta ei luo toistokopioita.

Elinkaaren toisessa päässä DELETE /v1/transcriptions/{id} pyyhkii yhdellä kutsulla kaiken yhteen työhön liittyvän. Ajastettu skenaario, joka lukee samasta data storesta säilytysaikaasi vanhemmat työtunnisteet ja poistaa ne, on neljä moduulia — ja se tekee säilytyskäytännöstäsi jotain, jonka voit näyttää sen sijaan että kuvailisit sitä.

Milloin pollaus on yhä oikea vastaus

Kolme tapausta puoltaa sitä aidosti: et voi tarjota webhookia ulospäin, tarvitset litteroinnin saman suorituksen sisällä vastataksesi synkroniseen pyyntöön, tai ajat kertaluonteista takautuvaa ajoa, jossa operaatioiden määrällä ei ole väliä.

Lisää siinä tapauksessa Tools → Sleep -moduuli ja tilan tarkistus osoitteeseen GET /v1/transcriptions/{id}, ja kunnioita kahta kattoa: Sleep on rajattu 300 sekuntiin moduulia kohden ja skenaarion suoritus 40 minuuttiin. Kysele 20–30 sekunnin välein viiden sijaan — vastauksessa on kenttä progress, joka kertoo todellisen kohdan putkessa, joten hitaampikin silmukka antaa sinulle jotain rehellistä näytettäväksi.

Jos haluat mieluummin nähdä tuon kuvion kunnolla rakennettuna, tämän oppaan n8n-versio käyttää pollausta alusta loppuun, koska itse ylläpidetyllä palvelimella silmukka on ilmainen.

Mikä puree sinua ennen pitkää

Taulukot alkavat ykkösestä. files[1] on ensimmäinen tiedosto. files[0] palauttaa tyhjän sen sijaan että kaatuisi.

Pass-through ja jäsennys ovat vaihtokauppa. Et voi varmentaa allekirjoitusta runkoa vastaan, jonka Make on jo jäsentänyt. Pass-through ja sen perään Parse JSON -moduuli on ainoa oikea järjestys.

Kutsurajat. 300 lukua ja 60 kirjoitusta minuutissa avainta kohden. Runsaasti normaaliin käyttöön, helppo saavuttaa jos levität koko arkiston rinnakkaisiin skenaarioajoihin. Käsittele takautuvat ajot erissä.

Lähdeosoitteiden on oltava saavutettavissa. Rajapinta luotaa median ennen kuin ottaa työn vastaan — juuri niin kesto ja hinta tiedetään etukäteen. Drive-linkki, joka vaatii kirjautumisen, palauttaa unreadable_source, eikä mitään veloiteta. Käytä suoria tai allekirjoitettuja osoitteita.

Kaikki lasketaan. Sleep-moduulit, reitittimet, iteratorin kierrokset ja läpi päästävät suodattimet kuluttavat kaikki operaatioita. Kun skenaario tuntuu kalliilta, laske moduulit ennen kuin syytät rajapintaa.

Valmis vastaanotin

Tässä on blueprintin runko. Tuo se sisään ja kiinnitä sitten oma webhookisi ja toimitusmoduulisi — ja käytä Maken yhteyksien hallintaa sen sijaan että liimaisit avaimen moduuliin.

{
  "name": "Inwista — transcript receiver",
  "flow": [
    {
      "id": 1,
      "module": "gateway:CustomWebHook",
      "version": 1,
      "parameters": { "hook": 0, "maxResults": 1 },
      "mapper": {},
      "metadata": { "designer": { "x": 0, "y": 0 } }
    },
    {
      "id": 2,
      "module": "json:ParseJSON",
      "version": 1,
      "parameters": { "type": 0 },
      "mapper": { "json": "{{1.data}}" },
      "metadata": { "designer": { "x": 300, "y": 0 } }
    },
    {
      "id": 3,
      "module": "http:ActionGetFile",
      "version": 3,
      "parameters": {},
      "mapper": { "url": "{{2.files[1].url}}", "serializeUrl": false },
      "metadata": { "designer": { "x": 600, "y": 0 } }
    }
  ],
  "metadata": {
    "instant": true,
    "version": 1,
    "scenario": { "roundtrips": 1, "maxErrors": 3, "autoCommit": true },
    "designer": { "orphans": [] }
  }
}

Kolme moduulia. Pollaavassa vastineessa niitä oli yksitoista, ja sen ajaminen maksoi kuusinkertaisesti.

Mitä tämä oikeasti muuttaa

Automaation mitta ei ole se, mitä se tekee sinun katsoessasi. Mitta on se, mitä se tekee sunnuntaina kello kaksi yöllä, kun yhdeksänkymmenen minuutin tallenne saapuu eikä kukaan ole hereillä.

Skenaario, joka pyörii neljä minuuttia tiedostoa kohden ja polttaa operaatioita kysyäkseen kysymystä, jonka vastauksen se jo tietää, on jotain jota päädyt lopulta tarkkailemaan. Vastaanotin, joka herää, varmentaa allekirjoituksen, kirjoittaa tiedoston ja nukahtaa takaisin, on jotain jonka olemassaolon unohdat — ja sen unohtaminen on koko pointti.

Siinä vaiheessa tekstitykset lakkaavat olemasta tehtävä, joka on jonkun vastuulla. Niistä tulee jokaisen organisaatiosi tuottaman tallenteen ominaisuus: haettava, saavutettava, vaatimustenmukainen — eikä kenenkään tarvinnut kutsua siitä palaveria.

Valmis rakentamaan sen? Luo API-avain — ilmaistaso riittää tämän ajamiseen alusta loppuun. Täydellinen päätepisteiden viitedokumentaatio löytyy API-dokumentaatiosta.