Webhooky: HMAC podpis, opakované doručování a osvědčené postupy
Jak přijímat výsledky přepisů přes webhook: HMAC-SHA256 podpis, hlavičky X-VPT-Signature a X-VPT-Event, 6 pokusů o opakované doručení s backoffem.
Místo neustálého dotazování API, zda přepis skončil, v požadavku zadáte webhook_url a VoxScriber odešle POST na váš server ve chvíli, kdy je úloha dokončena – ať už úspěšně, nebo s chybou. Toto je doporučený způsob integrace: spotřebujete méně požadavků a výsledek dorazí okamžitě.
Jak to funguje
- Pošlete zvukový soubor s
webhook_url(povinně přeshttps). - Po dokončení zpracování odešleme na tuto URL POST s výsledkem.
- Váš server odpoví stavem
2xx, čímž potvrdí přijetí.
Každé doručení obsahuje dvě identifikační hlavičky:
| Hlavička | Obsah |
|---|---|
X-VPT-Event | Typ události (dokončení, selhání atd.) |
X-VPT-Signature | HMAC-SHA256 podpis doručení |
Před tím, než obsahu začnete věřit, vždy ověřte podpis: spočítejte HMAC-SHA256 z přijatého těla a porovnejte ho s hodnotou hlavičky X-VPT-Signature. Požadavek bez platného podpisu musí být zahozen – URL vašeho endpointu může zjistit kdokoli.
Automatické opakované doručování
Pokud je váš endpoint nedostupný nebo odpovídá příliš pomalu, zkusíme to znovu:
- Časový limit na pokus: 15 sekund.
- Maximální počet pokusů: 6.
- Čekání mezi pokusy (backoff): 5 min → 30 min → 2 h → 6 h → 24 h.
Všechna doručení jsou u nás trvale uložená, takže pokud se něco ztratí, můžete historii zkontrolovat s podporou.
Na webhook odpovězte okamžitě stavem 200 a obsah zpracovávejte asynchronně (fronta, úloha). Pokud zpracování trvá déle než 15 sekund, doručení se počítá jako selhání a zařadí se do fronty opakovaného doručení – a stejnou událost můžete obdržet dvakrát. Zpracovávejte události idempotentně.
Vždy obdržíte závěrečný výsledek
Zaseknuté úlohy nezmizí tiše:
- Úloha ve frontě, která čeká déle než 10 minut, je automaticky zařazena znovu do fronty.
- Úloha ve zpracování, která je zaseknutá déle než 60 minut, je označena jako neúspěšná – a na vaši URL je odeslán chybový webhook.
Jinými slovy: pro každé odeslané audio obdrží váš systém konečný callback – při úspěchu i při selhání.
FAQ
Můj server byl nedostupný. Přišel jsem o výsledek?
Pravděpodobně ne: proběhne až 6 pokusů rozložených do ~24 hodin. Pokud všechny selžou, historie doručení je stále uložená – kontaktujte podporu a nechte si to zpracovat znovu.
Můžu použít URL http (bez TLS)?
Ne. Z bezpečnostních důvodů přijímáme pouze URL https, bez přesměrování, a interní/soukromé adresy jsou blokované.
Jak rozeznám webhook s úspěchem od webhooku s chybou?
Podle hlavičky X-VPT-Event, která určuje typ události, a podle obsahu těla doručení.
Co musí můj endpoint odpovědět?
Jakýkoli stav 2xx do 15 sekund. Ostatní stavy (nebo vypršení časového limitu) se počítají jako selhání a vedou k opakovanému doručení.