Webhooks: HMAC-signatur, genlevering og bedste praksis
Sådan modtager du transkriptionsresultatet via webhook: HMAC-SHA256-signatur, X-VPT-Signature og X-VPT-Event-headere, 6 leveringsforsøg med backoff.
I stedet for at blive ved med at spørge API'en, om transkriptionen er færdig, angiver du en webhook_url i anmodningen, og VoxScriber sender en POST til din server, når jobbet er afsluttet – med succes eller med fejl. Det er den anbefalede måde at integrere på: det bruger færre anmodninger, og resultatet ankommer med det samme.
Sådan fungerer det
- Du sender lyden med en
webhook_url(obligatoriskhttps). - Når behandlingen er færdig, sender vi en POST til den URL med resultatet.
- Din server svarer med en
2xx-status for at bekræfte modtagelsen.
Hver levering indeholder to identifikations-headere:
| Header | Indhold |
|---|---|
X-VPT-Event | Begivenhedstypen (afslutning, fejl osv.) |
X-VPT-Signature | HMAC-SHA256-signatur for leveringen |
Valider altid signaturen, før du stoler på indholdet: beregn HMAC-SHA256 af den modtagne krop, og sammenlign den med værdien i X-VPT-Signature-headeren. En anmodning uden en gyldig signatur skal kasseres – hvem som helst kan finde URL'en på dit endpoint.
Automatiske genleveringer
Hvis dit endpoint er nede eller bruger for lang tid, prøver vi igen:
- Timeout pr. forsøg: 15 sekunder.
- Maks. antal forsøg: 6.
- Ventetid mellem forsøg (backoff): 5 min → 30 min → 2 t → 6 t → 24 t.
Alle leveringer gemmes hos os, så du kan gennemgå historikken med support, hvis noget skulle gå tabt.
Svar straks på webhooken med 200, og behandl indholdet asynkront (kø, job). Hvis behandlingen tager mere end 15 sekunder, tæller leveringen som en fejl og havner i genleveringskøen – og du kan ende med at modtage den samme begivenhed to gange. Håndter begivenhederne idempotent.
Du får altid et endeligt resultat
Jobs, der går i stå, forsvinder ikke lydløst:
- Et job i køen, der har stået stille i mere end 10 minutter, bliver automatisk sat i kø igen.
- Et job i behandling, der har kørt fast i mere end 60 minutter, markeres som fejlet – og udløser en fejl-webhook til din URL.
Med andre ord: for hver lyd, du sender, modtager dit system et endeligt callback – med succes eller fejl.
FAQ
Min server var nede. Har jeg mistet resultatet?
Sandsynligvis ikke: der er op til 6 forsøg fordelt over cirka 24 timer. Hvis alle fejler, bliver leveringshistorikken registreret – kontakt support for at få behandlet den igen.
Kan jeg bruge en http-URL (uden TLS)?
Nej. Af sikkerhedsmæssige årsager accepterer vi kun https-URL'er uden omdirigeringer, og interne/private adresser er blokeret.
Hvordan skelner jeg mellem en succes-webhook og en fejl-webhook?
Via X-VPT-Event-headeren, som identificerer begivenhedstypen, og via indholdet i leveringskroppen.
Hvad skal mit endpoint svare?
Enhver 2xx-status inden for 15 sekunder. Andre statuskoder (eller timeout) tæller som fejl og udløser en genlevering.
Relaterede artikler
Løste det ikke dit problem? Åbn en ticket – vores team svarer hurtigt.