Konfiguracja webhooków TikTok API for Business
Webhooki TikTok API for Business trafiają na jeden adres wywołania zwrotnego dla każdej aplikacji dewelopera i typu zdarzenia, ustawiany poleceniem POST /business/webhook/update/ z app_id i secret aplikacji. event_type VIDEO subskrybuje cztery zdarzenia publikacji posta, a COMMENT zdarzenie comment.update. Każde dostarczenie to żądanie HTTPS POST podpisane w nagłówku Tiktok-Signature kodem HMAC-SHA256 z kluczem będącym sekretem aplikacji.
easyCoexistence utrzymuje subskrypcję webhooka komentarzy TikTok dla swojej aplikacji, sprawdza podpis TikTok i przekazuje każde zdarzenie komentarza dla Twojego konta na Twój endpoint HTTPS, podpisane własnym sekretem.
Jak długo TikTok ponawia dostarczenie, na które nie otrzymano odpowiedzi HTTP 200, z wykładniczym wydłużaniem przerw, zanim je odrzuci.
Najwięcej identyfikatorów postów, jakie jeden item_list może wskazać, aby ograniczyć zdarzenia comment.update do wybranych postów.
Aktualna wartość nagłówka webhook-schema-version, który TikTok wysyła z każdym dostarczeniem.
Co referencja TikTok podaje dla endpointów konfiguracji webhooków, uwierzytelnianych identyfikatorem i sekretem aplikacji.
Algorytm stojący za Tiktok-Signature: znacznik czasu, kropka i treść, kluczowane sekretem aplikacji i zakodowane szesnastkowo.
Uprawnienie aplikacji w sekcji TikTok Accounts potrzebne dla comment.update; zdarzenia publikacji wymagają Business Content.
Które zdarzenia webhooków może odbierać aplikacja konta TikTok?
Dwie kategorie, każda subskrybowana jako osobny event_type. VIDEO obejmuje posty opublikowane przez /business/video/publish/ lub /business/photo/publish/, a COMMENT obejmuje komentarze pod postami zdjęciowymi konta i publicznymi postami wideo, niezależnie od tego, czy opublikowano je przez API, czy w aplikacji TikTok:
Czego potrzebuje aplikacja przed subskrypcją?
Dostępu do API for Business, aplikacji deweloperskiej oraz kont TikTok, które ją autoryzowały. Przewodnik subskrypcji TikTok dodaje uprawnienie dla każdej kategorii, a zdarzenie komentarzy wymaga zakresu od każdego właściciela:
- Zdarzenia publikacji: uprawnienie TikTok Accounts, Business Content w aplikacji.
- Zdarzenia komentarzy: uprawnienie TikTok Accounts, Business Comment w aplikacji.
- comment.update: zakres comment.list, nadany przez właściciela i utrzymywany w ważności.
- Adres wywołania zwrotnego w HTTPS, który od razu odpowiada HTTP 200.
Jak zasubskrybować?
Poleceniem POST do /business/webhook/update/, raz dla każdego event_type. Ciało żądania przyjmuje app_id i secret, event_type, VIDEO lub COMMENT, oraz callback_url; dla COMMENT może też przyjąć item_list. Odpowiedź powtarza app_id, event_type, callback_url oraz, jeśli jest ustawiona, item_list. Ponowne wywołanie dla tego samego event_type zastępuje adres wywołania zwrotnego.
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/business/webhook/update/' \
-H 'Content-Type: application/json' \
-d '{
"app_id": "<APP_ID>",
"secret": "<APP_SECRET>",
"event_type": "COMMENT",
"callback_url": "https://hooks.example.com/tiktok/"
}'
{
"code": 0,
"message": "OK",
"request_id": "<REQUEST_ID>",
"data": { "app_id": "<APP_ID>", "callback_url": "https://hooks.example.com/tiktok/", "event_type": "COMMENT" }
}Jak item_list zawęża zdarzenia komentarzy?
Ogranicza comment.update do wskazanych postów, do 100 identyfikatorów z /business/video/list/, a pierwsza lista rozstrzyga o trybie aplikacji od tej chwili:
- Pierwsze wywołanie COMMENT z
item_list: zdarzenia przychodzą tylko dla wymienionych postów. - Kolejne wywołania z
item_list: nowe posty dołączają do już wymienionych. - Wywołanie COMMENT bez
item_list, gdy wcześniej nic nie ustawiono: zdarzenia przychodzą dla postów kont, które autoryzowały aplikację. - Wywołanie COMMENT bez
item_list, gdy lista już istnieje: skonfigurowane posty pozostają bez zmian.
Jak sprawdzić lub usunąć subskrypcję?
GET /business/webhook/list/ z app_id, secret i event_type zwraca konfigurację: callback_url pojawia się tylko wtedy, gdy dla tego typu zdarzenia istnieje, a item_list tylko wtedy, gdy został ustawiony. POST /business/webhook/delete/ z app_id, secret i event_type usuwa ją; dla COMMENT item_list w wywołaniu usunięcia usuwa tylko te posty, a bez niego zdarzenia komentarzy ustają dla wszystkich postów.
Co musi robić adres wywołania zwrotnego?
Odpowiadać natychmiast. TikTok wysyła POST z JSON przez HTTPS i traktuje wszystko poza HTTP 200 jako nieudane dostarczenie, ponawiając z wykładniczym wydłużaniem przerw przez maksymalnie 72 godziny, zanim odrzuci zdarzenie. Dostarczenie odbywa się co najmniej raz, więc to samo zdarzenie może przyjść dwukrotnie, a przetwarzanie musi być idempotentne. Każde żądanie niesie trzy nagłówki warte zapisywania w logach: tiktok-signature, webhook-schema-version i x-tt-logid. W treści znajdują się client_key, event, create_time (w sekundach), user_openid, czyli business_id konta, oraz content, zserializowany ciąg JSON.
Jak sprawdzić Tiktok-Signature?
Rozdziel nagłówek, t=<unix>,s=<hex>, najpierw po przecinkach, a potem po znaku równości. Zbuduj podpisaną wiadomość z wartości t, kropki i ciała żądania, oblicz z niej HMAC-SHA256 kluczowany sekretem aplikacji, zakoduj szesnastkowo i porównaj z s. Następnie sprawdź, jak stary jest t: TikTok podpisuje czas dostarczenia, by uniemożliwić ponowne odtworzenie, a jego przykład akceptuje opóźnienie do 5 sekund. Praca na surowym ciele żądania, dokładnie w takiej postaci, w jakiej przyszło, zapobiega odmiennej ponownej serializacji JSON.
import hashlib, hmac, time
def verify_tiktok(raw_body: bytes, header: str, app_secret: str, max_age: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, s = parts.get("t", ""), parts.get("s", "")
if not t.isdigit():
return False
expected = hmac.new(app_secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, s) and abs(time.time() - int(t)) <= max_ageJak odbierać zdarzenia TikTok przez easyCoexistence?
Podając kontu adres docelowy. easyCoexistence utrzymuje własną aplikację zasubskrybowaną do COMMENT, sprawdza podpis TikTok, od razu odpowiada TikTokowi i wysyła każde comment.update dla podłączonego konta na adres HTTPS ustawiony dla niego. Z poziomu Claude lub ChatGPT set_social_webhook_destination przyjmuje account_id i url, albo null, by przestać, i zwraca sekret podpisu pokazywany tylko raz; ponowne wywołanie wydaje nowy. Zdarzenia publikacji nie są przekazywane: zamiast nich get_tiktok_publish_status śledzi post.
set_social_webhook_destination { "account_id": "<ACCOUNT_ID>", "url": "https://hooks.example.com/tiktok/" }
=> {
"url": "https://hooks.example.com/tiktok/",
"signing_secret": "whsec_<SECRET>",
"note": "Shown once: store it as a secret. ..."
}Jak ustawić to przez Partner API?
Poleceniem PUT /channels/{id}/webhook na https://easycoexistence.com/api/v1, kluczem ec_live_ jako tokenem bearer i treścią {"url": "https://..."}. Odpowiedź zawiera webhook_url, signing_secret i note, a {"url": null} zatrzymuje przekazywanie. Adres musi używać HTTPS na publicznym hoście; nieznany kanał zwraca 404 not_found, usunięty 409 removed, a zawieszony 402 suspended.
curl -X PUT "https://easycoexistence.com/api/v1/channels/$CHANNEL_ID/webhook" \
-H "Authorization: Bearer $EC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://hooks.example.com/tiktok/"}'
{ "webhook_url": "https://hooks.example.com/tiktok/", "signing_secret": "whsec_<SECRET>", "note": "..." }Czym różnią się oba dostarczenia?
Przekazanie z easyCoexistence jest podpisane i ukształtowane inaczej niż własne dostarczenie TikTok, więc odbiorca napisany pod jedno wymaga zmian dla drugiego. Przekazana treść zachowuje pola komentarza TikTok, z content po sparsowaniu i identyfikatorami jako ciągami znaków; zmienia się sposób podpisywania, zakresu i ponawiania każdego dostarczenia:
| TikTok to your app | easyCoexistence to your endpoint | |
|---|---|---|
| Header | Tiktok-Signature: t=<unix>,s=<hex> | X-EC-Signature: t=<unix>,v1=<hex> |
| Key | The developer app's secret | The account's signing secret, shown once |
| Events | VIDEO and COMMENT, per app | comment.update, per connected account |
| Body | client_key, event, create_time, user_openid, content as a string | platform, account_id, external_id, entry with content parsed |
| Retries | Up to 72 hours | None: one attempt, 8 seconds, no redirects |
Jak to skonfigurować
- Grant the permissionsGive the developer app Business Content for publishing events and Business Comment for comment events, and have owners grant comment.list.
- Build the callbackServe an HTTPS endpoint that checks Tiktok-Signature and replies 200 before doing any work.
- Subscribe each event typeCall /business/webhook/update/ with app_id, secret, event_type and callback_url, once for VIDEO and once for COMMENT.
- Confirm the configurationCall /business/webhook/list/ for each event_type and check that the callback_url, and any item_list, came back.
- Handle repeatsKey each event on its content, such as comment_id with comment_action, or publish_id with the event name, before acting on it.
Typowe błędy
- Przetwarzanie zdarzenia przed odpowiedzią. TikTok oczekuje natychmiastowego HTTP 200 i ponawia dostarczenia, których nie widzi potwierdzonych, więc zakolejkuj pracę i najpierw odpowiedz.
- Przypadkowe wysłanie item_list przy pierwszej subskrypcji COMMENT. Od tej chwili TikTok zgłasza zdarzenia komentarzy tylko dla wymienionych postów.
- Weryfikacja tokenem dostępu. TikTok podpisuje webhooki sekretem aplikacji, tym samym, który przyjmuje /business/webhook/update/.
- Wskazywanie dwóch środowisk na jedną aplikację. Każdy typ zdarzenia ma jeden callback_url na aplikację, a nowe wywołanie /business/webhook/update/ go zastępuje.
Ustaw je poleceniem set_social_webhook_destination z Claude lub ChatGPT albo przez PUT /channels/{id}/webhook. Od US$ 9 do US$ 0,75 za połączenie miesięcznie, taniej w miarę dodawania połączeń, a pierwsze 3 dni są bezpłatne.
Najczęściej zadawane pytania
Jakie nagłówki niesie dostarczenie webhooka TikTok?
tiktok-signature, webhook-schema-version, obecnie v1.0, oraz x-tt-logid, identyfikator dostarczenia. Treść JSON zawiera client_key, event, create_time, user_openid i content.
Czy TikTok wysyła webhook po opublikowaniu wideo?
Tak, z event_type VIDEO: post.publish.complete, gdy TikTok pobierze i sprawdzi plik, a następnie post.publish.publicly_available z post_id, gdy post stanie się publiczny.
Jak długo TikTok ponawia nieudany webhook?
Do 72 godzin z wykładniczym wydłużaniem przerw, po czym zdarzenie jest odrzucane. Dostarczenie odbywa się co najmniej raz, więc spodziewaj się duplikatów.
Czy mogę zarejestrować własny callback w aplikacji TikTok easyCoexistence?
Nie. Ustawienia webhooków aplikacji pozostają w easyCoexistence. set_social_webhook_destination kieruje zamiast tego zdarzenia komentarzy konta do Ciebie.
Czytaj dalej
Połącz pierwszy kanał w dwie minuty.
Bez czekania na weryfikację przez platformy. Połącz WhatsApp, Instagram, TikTok lub inny kanał, a potem poproś swoją AI o opublikowanie posta, odpowiedź lub raport i zobacz, jak działa.
- 3 dni za darmo
- Rezygnacja w każdej chwili
- Tylko oficjalne API
- Monitorowanie 24/7
Zweryfikowano w