Webhooks: HMAC-signatur, återleveranser och bästa praxis
Så här tar du emot transkriptionsresultat via webhook: HMAC-SHA256-signatur, rubrikerna X-VPT-Signature och X-VPT-Event, 6 återleveransförsök med backoff.
Istället för att kontinuerligt fråga API:t om transkriptionen är klar anger du en webhook_url i begäran, så skickar VoxScriber en POST till din server när jobbet är klart — antingen med framgång eller med fel. Det är det rekommenderade sättet att integrera: det förbrukar färre anrop och resultatet kommer direkt.
Så här fungerar det
- Du skickar ljudet med en
webhook_url(måste varahttps). - När bearbetningen är klar skickar vi en POST till den URL:en med resultatet.
- Din server svarar med status
2xxför att bekräfta att meddelandet tagits emot.
Varje leverans har två identifierings-headers:
| Header | Innehåll |
|---|---|
X-VPT-Event | Typ av händelse (slutförd, misslyckad osv.) |
X-VPT-Signature | Leveransens HMAC-SHA256-signatur |
Validera alltid signaturen innan du litar på innehållet: beräkna HMAC-SHA256 på den mottagna kroppen och jämför med värdet i header X-VPT-Signature. En begäran utan giltig signatur ska kasseras — vem som helst kan lista ut URL:en till din endpoint.
Automatiska återleveranser
Om din endpoint ligger nere eller svarar för långsamt gör vi nya försök:
- Tidsgräns per försök: 15 sekunder.
- Maximalt antal försök: 6.
- Väntan mellan försök (backoff): 5 min → 30 min → 2 h → 6 h → 24 h.
Alla leveranser sparas hos oss, så det går att granska historiken med supporten om något försvinner.
Svara på webhooken omedelbart med 200 och bearbeta innehållet asynkront (kö, jobb). Om din bearbetning tar mer än 15 sekunder räknas leveransen som misslyckad och hamnar i kön för återleverans — och du kan komma att få samma händelse två gånger. Hantera händelserna idempotent.
Du får alltid ett slutgiltigt utfall
Hängande jobb försvinner inte i tysthet:
- Ett jobb i kön som stått stilla i mer än 10 minuter köas om automatiskt.
- Ett bearbetande jobb som hängt i mer än 60 minuter markeras som misslyckat — och skickar en fel-webhook till din URL.
Med andra ord: för varje skickat ljud får ditt system en slutlig callback, antingen för framgång eller för misslyckande.
FAQ
Min server var nere. Har jag förlorat resultatet?
Troligtvis inte: det görs upp till 6 försök under cirka 24 timmar. Om alla misslyckas finns leveranshistoriken registrerad — kontakta supporten för att bearbeta om.
Kan jag använda en http-URL (utan TLS)?
Nej. Av säkerhetsskäl accepterar vi endast https-URL:er, utan omdirigeringar, och interna/privata adresser blockeras.
Hur skiljer jag en framgångsrik webhook från en felwebhook?
Via header X-VPT-Event, som identifierar händelsetypen, och via innehållet i leveransens body.
Vad behöver min endpoint svara?
Valfri 2xx-status inom 15 sekunder. Andra statusar (eller timeout) räknas som misslyckande och utlöser återleverans.
Relaterade artiklar
Inte löst? Öppna ett ärende — vårt team svarar snabbt.