Webhooki: Podpis HMAC, ponowne dostarczanie i dobre praktyki
Jak odbierać wyniki transkrypcji przez webhook: podpis HMAC-SHA256, nagłówki X-VPT-Signature i X-VPT-Event, 6 prób ponownego dostarczenia z backoffem.
Zamiast ciągle odpytywać API, aby sprawdzić, czy transkrypcja się zakończyła, podajesz webhook_url w żądaniu, a VoxScriber wysyła POST na Twój serwer, gdy zadanie zostanie ukończone — z powodzeniem lub z błędem. To zalecany sposób integracji: zużywasz mniej żądań, a wynik dociera natychmiast.
Jak to działa
- Wysyłasz audio z parametrem
webhook_url(obowiązkowohttps). - Gdy przetwarzanie się zakończy, wysyłamy POST na ten adres URL z wynikiem.
- Twój serwer odpowiada statusem
2xx, aby potwierdzić otrzymanie.
Każda dostawa zawiera dwa nagłówki identyfikacyjne:
| Nagłówek | Zawartość |
|---|---|
X-VPT-Event | Typ zdarzenia (zakończenie, błąd itp.) |
X-VPT-Signature | Podpis HMAC-SHA256 dostawy |
Zawsze weryfikuj podpis, zanim zaufasz treści: oblicz HMAC-SHA256 otrzymanego ciała i porównaj z wartością nagłówka X-VPT-Signature. Żądanie bez prawidłowego podpisu należy odrzucić — każdy może poznać URL Twojego endpointu.
Automatyczne ponowne dostarczanie
Jeśli Twój endpoint jest niedostępny lub odpowiada zbyt wolno, próbujemy ponownie:
- Limit czasu na próbę: 15 sekund.
- Maksymalna liczba prób: 6.
- Odstępy między próbami (backoff): 5 min → 30 min → 2 h → 6 h → 24 h.
Wszystkie dostawy są przechowywane po naszej stronie, więc można przeanalizować historię z pomocą wsparcia, jeśli coś zaginie.
Odpowiadaj na webhook natychmiast kodem 200 i przetwarzaj treść asynchronicznie (kolejka, zadanie). Jeśli przetwarzanie zajmie więcej niż 15 sekund, dostawa zostanie uznana za nieudaną i trafi do kolejki ponownych prób — możesz wtedy otrzymać to samo zdarzenie dwukrotnie. Przetwarzaj zdarzenia w sposób idempotentny.
Zawsze otrzymujesz wynik końcowy
Zadania, które utkną, nie znikają po cichu:
- Zadanie w kolejce oczekujące dłużej niż 10 minut jest automatycznie umieszczane ponownie w kolejce.
- Zadanie w trakcie przetwarzania zablokowane dłużej niż 60 minut jest oznaczane jako nieudane — i wyzwala webhook błędu na Twój URL.
Innymi słowy: dla każdego wysłanego audio Twój system otrzymuje końcowe wywołanie zwrotne, sukcesu lub błędu.
FAQ
Mój serwer był niedostępny. Czy straciłem wynik?
Prawdopodobnie nie: jest do 6 prób rozłożonych na ~24 godziny. Jeśli wszystkie zawiodą, historia dostaw pozostaje zapisana — skontaktuj się ze wsparciem w celu ponownego przetworzenia.
Czy mogę użyć adresu URL http (bez TLS)?
Nie. Ze względów bezpieczeństwa akceptujemy wyłącznie adresy URL https, bez przekierowań, a adresy wewnętrzne/prywatne są blokowane.
Jak odróżnić webhook sukcesu od błędu?
Po nagłówku X-VPT-Event, który identyfikuje typ zdarzenia, oraz po zawartości treści dostawy.
Co musi odpowiedzieć mój endpoint?
Dowolny status 2xx w ciągu 15 sekund. Inne statusy (lub przekroczenie czasu) są uznawane za błąd i powodują ponowną próbę dostarczenia.
Powiązane artykuły
Nie znalazłeś rozwiązania? Otwórz zgłoszenie — nasz zespół szybko odpowiada.