Webhookit: HMAC-allekirjoitus, uudelleenlähetykset ja hyvät käytännöt
Kuinka vastaanotat transkriptioiden tulokset webhookilla: HMAC-SHA256-allekirjoitus, X-VPT-Signature- ja X-VPT-Event-otsikot, 6 uudelleenlähetysyritystä backoffilla.
Sen sijaan, että kyselisit API:lta, onko transkriptio valmistunut, annat webhook_url-osoitteen pyynnössä, ja VoxScriber lähettää POST-pyynnön palvelimellesi, kun työ on valmis — onnistuneesti tai virheellä. Tämä on suositeltu tapa integroida: se kuluttaa vähemmän pyyntöjä ja tulos saapuu heti.
Kuinka se toimii
- Lähetät äänen
webhook_url-osoitteella (pakollisestihttps). - Kun käsittely on valmis, lähetämme POST-pyynnön tähän URL-osoitteeseen tuloksen kanssa.
- Palvelimesi vastaa
2xx-tilakoodilla kuittaaksesi vastaanoton.
Jokainen toimitus sisältää kaksi tunnistusotsikkoa:
| Otsikko | Sisältö |
|---|---|
X-VPT-Event | Tapahtuman tyyppi (valmistuminen, virhe jne.) |
X-VPT-Signature | Toimituksen HMAC-SHA256-allekirjoitus |
Varmista aina allekirjoitus ennen kuin luotat sisältöön: laske HMAC-SHA256 vastaanotetusta rungosta ja vertaa sitä X-VPT-Signature-otsikon arvoon. Ilman kelvollista allekirjoitusta oleva pyyntö tulee hylätä — kuka tahansa voi selvittää päätepisteesi URL-osoitteen.
Automaattiset uudelleenlähetykset
Jos päätepisteesi on alhaalla tai vastaa liian hitaasti, yritämme uudelleen:
- Aikakatkaisu yritystä kohden: 15 sekuntia.
- Enimmäismäärä yrityksiä: 6.
- Odotus yritysten välillä (backoff): 5 min → 30 min → 2 h → 6 h → 24 h.
Kaikki toimitukset säilytetään meidän päässämme, joten historiaa voidaan auditoida tuen kanssa, jos jokin katoaa.
Vastaa webhookiin välittömästi 200-tilakoodilla ja käsittele sisältö asynkronisesti (jono, työ). Jos käsittelysi kestää yli 15 sekuntia, toimitus katsotaan epäonnistuneeksi ja se menee uudelleenlähetysjonoon — ja saatat saada saman tapahtuman kahdesti. Käsittele tapahtumat idempotentisti.
Saat aina lopputuloksen
Jumiutuneet työt eivät katoa hiljaisuudessa:
- Yli 10 minuuttia jonossa pysähtynyt työ asetetaan automaattisesti uudelleen jonoon.
- Yli 60 minuuttia käsittelyssä jumiutunut työ merkitään epäonnistuneeksi — ja se laukaisee virhewebhookin URL-osoitteeseesi.
Eli: jokaisesta lähetetystä äänestä järjestelmäsi saa lopullisen callbackin, onnistumisen tai virheen.
FAQ
Palvelimeni oli alhaalla. Menetinkö tuloksen?
Todennäköisesti et: yrityksiä on enintään 6 jakautuneena noin 24 tunnin ajalle. Jos kaikki epäonnistuvat, toimitushistoria tallentuu — ota yhteyttä tukeen, niin voimme käsitellä uudelleen.
Voinko käyttää http-URL-osoitetta (ilman TLS:ää)?
Et. Turvallisuussyistä hyväksymme vain https-URL-osoitteet ilman uudelleenohjauksia, ja sisäiset/yksityiset osoitteet on estetty.
Kuinka erotan onnistuneen webhookin virheellisestä?
X-VPT-Event-otsikon perusteella, joka kertoo tapahtuman tyypin, sekä toimituksen rungon sisällöstä.
Mihin päätepisteeni pitää vastata?
Mikä tahansa 2xx-tilakoodi 15 sekunnin kuluessa. Muut tilakoodit (tai aikakatkaisu) lasketaan virheeksi ja aiheuttavat uudelleenlähetyksen.
Aiheeseen liittyvät artikkelit
Eikö ongelma ratkennut? Avaa tukipyyntö — tiimimme vastaa nopeasti.