Webhooki w sekcji „Awatary wideo”: powiadomienie na Twój serwer, gdy wideo będzie gotowe
Webhooki w sekcji „Awatary wideo” to sposób, aby dowiedzieć się, że film jest gotowy, bez konieczności ręcznego odświeżania strony: gdy tylko film zostanie ukończony, na adres Twojego serwera wysyłane jest żądanie POST, a Twój serwer sam decyduje, co dalej robić - napisz link do bazy danych, wyślij plik do klienta, czy też rozpocznij kolejny krok. Zakładka jest potrzebna tym, którzy nagrywają filmy partiami lub integrują generowanie awatarów ze swoim produktem: zamiast niekończących się kontroli „gotowe lub jeszcze nie”, jedno krótkie powiadomienie dociera dokładnie we właściwym momencie.
Dlaczego jest to w ogóle konieczne?
Renderowanie wideo nie jest operacją błyskawiczną i nie ma sensu czekać na nią w otwartej karcie. Według pomiarów platformy z dnia 09.07.2026 za pięciosekundowe wideo Kling 3.0 w rozdzielczości 1080p przyjmuje się średnio 115 sekund, a w 95% przypadków mieści się w 165. W przypadku Sory 2 to samo zadanie zajmuje średnio około 145 sekund. Jeśli sprawdzasz status co kilka sekund, w jednym filmie pojawiają się dziesiątki pustych żądań; Element webhook pojawia się tylko raz – kiedy faktycznie pojawia się wynik.
Głośność też mówi sama za siebie. Według dziennika generacji platformy, w ciągu 30 dni (3 września – 2 października 2026 r.) rozpoczęło się 3292 zadań wideo, z czego 2369 zakończyło się pomyślnie. Filmy są liczone w tle i kończą się w różnym czasie – nie można tego śledzić ręcznie, a zgrabna obsługa powiadomień sama rozwiązuje problem.
Do czego służy zakładka „Webhooks”?
Chodzi o dostarczanie powiadomień, bez magii. Rejestrujesz adres, wybierasz, które wydarzenia chcesz subskrybować i otrzymujesz sekret subskrypcji. Lista zarejestrowanych punktów końcowych jest tam przechowywana: możesz zobaczyć adres, wybrane zdarzenia, status i to, czy punkt końcowy ma sekret. Sekret można ponownie zwolnić (stary natychmiast przestanie działać) lub punkt końcowy można całkowicie usunąć.
Wydarzenie pochodzi wyłącznie z Twoich filmów: film innej osoby nie zostanie opublikowany, nawet jeśli został policzony w tym samym momencie. Dostępny jest także dziennik dostarczonych zdarzeń - wygodnie jest sprawdzić, czy coś rzeczywiście dotarło na Twój serwer.
Jak zacząć – krok po kroku
- Otwórz sekcję „Awatary wideo” i panel webhook pod bezpośrednim adresem /ru/avatars?tab=webhooki.
- Zaloguj się na swoje konto: ustawienie nie jest dostępne dla gości; po kliknięciu otworzy się okno logowania.
- W polu „Adres punktu końcowego” wpisz publiczny adres HTTPS swojego serwera, na przykład https://example.com/avatar-webhook. HTTP nie będzie działać – dostarczanie i podpisywanie są zaprojektowane dla bezpiecznego kanału.
- Zaznacz wymagane zdarzenia. Jeśli nic nie zaznaczysz, będziesz subskrybowany do wszystkich wydarzeń na raz.
- Kliknij „Dodaj punkt końcowy”. Zaraz po utworzeniu pojawi się sekret subskrypcji - skopiuj go i zapisz dla siebie: nie będzie już wyświetlany.
- Jeżeli nie posiadasz jeszcze własnego serwera, kliknij „Zastąp naszego odbiornika” – wtedy powiadomienia będą gromadzone w logu dostarczonych zdarzeń bezpośrednio w zakładce.
Jak upewnić się, że prośba pochodzi od nas, a nie jest fałszywa
Każdemu żądaniu towarzyszy nagłówek podpisu — jest to HMAC-SHA256, obliczony na podstawie surowej treści żądania jako Twój sekret. Ze swojej strony policz ten sam podpis i porównaj: jeśli nie pasuje, odrzucamy prośbę. Nasz odbiorca robi dokładnie to i odpowiada 401 na błędny podpis. Trzymaj sekret na serwerze, w zmiennych środowiskowych, a nie w kodzie klienta.
Co znajduje się w żądaniu
Treść to zwykły JSON z typem zdarzenia i danymi jednostki. Na przykład w przypadku gotowego wideo jest to zdarzenie BLK0 z identyfikatorem wideo w środku. Pełna lista dostępnych typów wydarzeń znajduje się w zakładce: możesz ją posortować i zostawić tylko to, czego naprawdę potrzebuje Twoja usługa.
Ile to kosztuje
Rejestracja punktu końcowego, ponowne wydanie sekretu, usunięcie i dziennik zdarzeń nie zapisują tokenów - jest to ustawienie powiadomień, a nie generowanie. Tokeny wydawane są tylko na sam film: cena w tokenach jest widoczna przed uruchomieniem, a jeśli zadanie się nie powiedzie, to, co zostało odpisane, zostaje zwrócone. Nie ma subskrypcji: nowi użytkownicy otrzymują tokeny startowe na pierwsze testy.
Z czym łączyć
- „Zadania wsadowe” — uruchomienie kilkudziesięciu filmów w jednym zadaniu; Webhook wyeliminuje potrzebę ręcznej kontroli gotowości.
- „Biblioteka multimediów” — przechowywanie kodów źródłowych i gotowych plików.
- „Tłumaczenie wideo” I „Cięcie klipu” — kolejne kroki po pokoleniu.
Często zadawane pytania
Który adres jest odpowiedni dla webhooka?
Tylko publiczny protokół HTTPS. Adresy lokalne i protokół HTTP nie są akceptowane: powiadomienie musi przejść bezpiecznym kanałem, a Twój serwer musi być dostępny z zewnątrz.
Czy można otrzymywać powiadomienia, jeśli nie ma serwera?
Tak. Kliknij „Zastąp naszego odbiorcę” – zdarzenia zostaną zgromadzone w logu „Dostarczone zdarzenia” w zakładce, można je przeglądać bez Twojego backendu.
Co zrobić, jeśli podpis się nie zgadza?
Sprawdź, czy czytasz HMAC-SHA256 z nieprzetworzonej treści żądania (a nie z przeanalizowanego JSON) i czy używasz bieżącego sekretu: po ponownym wydaniu stary natychmiast przestaje działać.
Czy to jest płatne?
Konfigurowanie webhooków nie powoduje odpisywania tokenów. Tokeny wydawane są wyłącznie na generację wideo – ich cena widoczna jest przed uruchomieniem; Nie ma subskrypcji, nowi użytkownicy otrzymują tokeny startowe.