Webhooks: HMAC-signatur, gjenleveringer og beste praksis
Hvordan motta transkripsjonsresultater via webhook: HMAC-SHA256-signatur, headere X-VPT-Signature og X-VPT-Event, 6 gjenleveringsforsøk med backoff.
I stedet for å spørre API-et om transkripsjonen er ferdig, oppgir du en webhook_url i forespørselen, og VoxScriber sender en POST til serveren din når jobben fullføres — med suksess eller med feil. Dette er den anbefalte måten å integrere på: det bruker færre forespørsler, og resultatet kommer med en gang.
Slik fungerer det
- Du sender lyden med en
webhook_url(obligatoriskhttps). - Når behandlingen er ferdig, sender vi en POST til denne URL-en med resultatet.
- Serveren din svarer med en
2xx-status for å bekrefte mottak.
Hver levering har to identifikasjonsheadere:
| Header | Innhold |
|---|---|
X-VPT-Event | Typen hendelse (fullføring, feil osv.) |
X-VPT-Signature | Leveringens HMAC-SHA256-signatur |
Valider alltid signaturen før du stoler på innholdet: beregn HMAC-SHA256 av mottatt body og sammenlign med verdien i headeren X-VPT-Signature. Forespørsler uten gyldig signatur skal forkastes — hvem som helst kan finne URL-en til endepunktet ditt.
Automatiske gjenleveringer
Hvis endepunktet ditt er nede eller svarer for sakte, prøver vi igjen:
- Tidsavbrudd per forsøk: 15 sekunder.
- Maks antall forsøk: 6.
- Ventetid mellom forsøk (backoff): 5 min → 30 min → 2 t → 6 t → 24 t.
Alle leveringer lagres på vår side, så det er mulig å revidere loggen med support hvis noe skulle gå tapt.
Svar på webhooken umiddelbart med 200 og behandle innholdet asynkront (kø, job). Hvis behandlingen din tar mer enn 15 sekunder, regnes leveringen som feilet og settes i kø for gjenlevering — og du kan ende opp med å motta den samme hendelsen to ganger. Håndter hendelsene idempotent.
Du får alltid et endelig utfall
Jobber som henger, forsvinner ikke i stillhet:
- En jobb i køen som har stått i mer enn 10 minutter, blir automatisk satt i kø igjen.
- En jobb under behandling som har hengt i mer enn 60 minutter, blir merket som mislykket — og utløser en feil-webhook til URL-en din.
Med andre ord: for hver lyd som sendes, mottar systemet ditt en endelig callback, enten med suksess eller med feil.
FAQ
Min server var nede. Mistet jeg resultatet?
Sannsynligvis ikke: det er opptil 6 forsøk fordelt over omtrent 24 timer. Hvis alle mislykkes, blir leveringshistorikken registrert — kontakt support for å få behandlet på nytt.
Kan jeg bruke en http-URL (uten TLS)?
Nei. Av sikkerhetshensyn godtar vi kun https-URL-er, uten omdirigeringer, og interne/private adresser er blokkert.
Hvordan skiller jeg en vellykket webhook fra en mislykket?
Via headeren X-VPT-Event, som identifiserer hendelsestypen, og innholdet i leveringen (body).
Hva må endepunktet mitt svare med?
En hvilken som helst 2xx-status innen 15 sekunder. Andre statuskoder (eller tidsavbrudd) regnes som feil og utløser gjenlevering.
Relaterte artikler
Løste ikke problemet? Åpne en ticket — teamet vårt svarer raskt.