Webhooks: HMAC-handtekening, herleveringen en goede praktijken
Hoe je het resultaat van transcripties via webhook ontvangt: HMAC-SHA256-handtekening, headers X-VPT-Signature en X-VPT-Event, 6 herleveringspogingen met backoff.
In plaats van steeds de API te raadplegen om te weten of de transcriptie klaar is, geef je een webhook_url op in de aanvraag en stuurt VoxScriber een POST naar jouw server wanneer de taak is voltooid — succesvol of met een fout. Dit is de aanbevolen manier om te integreren: het kost minder aanvragen en het resultaat komt meteen binnen.
Hoe het werkt
- Je verzendt de audio met een
webhook_url(verplichthttps). - Wanneer de verwerking is voltooid, sturen we een POST naar die URL met het resultaat.
- Jouw server antwoordt met een
2xx-status om de ontvangst te bevestigen.
Elke levering bevat twee identificatieheaders:
| Header | Inhoud |
|---|---|
X-VPT-Event | Het gebeurtenistype (voltooiing, fout, enz.) |
X-VPT-Signature | HMAC-SHA256-handtekening van de levering |
Valideer altijd de handtekening voordat je de inhoud vertrouwt: bereken de HMAC-SHA256 van de ontvangen body en vergelijk deze met de waarde van de header X-VPT-Signature. Een verzoek zonder geldige handtekening moet worden weggegooid — iedereen kan de URL van je endpoint ontdekken.
Automatische herleveringen
Als je endpoint niet bereikbaar is of te lang duurt, proberen we het opnieuw:
- Timeout per poging: 15 seconden.
- Maximaal aantal pogingen: 6.
- Wachttijd tussen pogingen (backoff): 5 min → 30 min → 2 h → 6 h → 24 h.
Alle leveringen worden aan onze kant bewaard, dus het is mogelijk om de geschiedenis met support te controleren als er iets verloren gaat.
Beantwoord de webhook onmiddellijk met 200 en verwerk de inhoud asynchroon (wachtrij, job). Als je verwerking langer dan 15 seconden duurt, telt de levering als mislukt en komt deze in de herleveringswachtrij — en je kunt uiteindelijk dezelfde gebeurtenis twee keer ontvangen. Verwerk gebeurtenissen idempotent.
Je ontvangt altijd een uitkomst
Jobs die vastlopen, verdwijnen niet zomaar:
- Een job in de wachtrij die langer dan 10 minuten stilstaat, wordt automatisch opnieuw in de wachtrij geplaatst.
- Een in verwerking job die langer dan 60 minuten vastzit, wordt als mislukt gemarkeerd — en activeert een fout-webhook naar jouw URL.
Met andere woorden: voor elke verzonden audio ontvangt je systeem een definitieve callback, succesvol of mislukt.
FAQ
Mijn server was offline. Ben ik het resultaat kwijt?
Waarschijnlijk niet: er zijn tot 6 pogingen verspreid over ~24 uur. Als ze allemaal mislukken, wordt de leveringsgeschiedenis bewaard — neem contact op met support om opnieuw te verwerken.
Kan ik een http-URL gebruiken (zonder TLS)?
Nee. Voor de veiligheid accepteren we alleen https-URL's, zonder omleidingen, en interne/privé-adressen zijn geblokkeerd.
Hoe maak ik onderscheid tussen een succes-webhook en een fout-webhook?
Via de header X-VPT-Event, die het gebeurtenistype identificeert, en via de inhoud van de leveringsbody.
Wat moet mijn endpoint antwoorden?
Elke 2xx-status binnen 15 seconden. Andere statussen (of timeout) tellen als mislukt en veroorzaken een herlevering.
Gerelateerde artikelen
Niet opgelost? Open een ticket — ons team reageert snel.