Zaloguj sięRozpocznij bezpłatny okres próbny
easyCoexistence Oficjalne API

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.

72 hours

Jak długo TikTok ponawia dostarczenie, na które nie otrzymano odpowiedzi HTTP 200, z wykładniczym wydłużaniem przerw, zanim je odrzuci.

100

Najwięcej identyfikatorów postów, jakie jeden item_list może wskazać, aby ograniczyć zdarzenia comment.update do wybranych postów.

v1.0

Aktualna wartość nagłówka webhook-schema-version, który TikTok wysyła z każdym dostarczeniem.

No permission

Co referencja TikTok podaje dla endpointów konfiguracji webhooków, uwierzytelnianych identyfikatorem i sekretem aplikacji.

HMAC-SHA256

Algorytm stojący za Tiktok-Signature: znacznik czasu, kropka i treść, kluczowane sekretem aplikacji i zakodowane szesnastkowo.

Business Comment

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:

post.publish.failedVIDEO: the post broke a format rule or its URL was blocked before the download finished
post.publish.completeVIDEO: the file met the format rules and downloaded without problems
post.publish.publicly_availableVIDEO: moderation passed and the post is public, with its post_id
post.publish.no_longer_publicly_availableVIDEO: later moderation, or the owner, took the post out of public view
comment.updateCOMMENT: a comment or reply created, deleted, hidden, set to friends only or made public

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.

Subscribe the app to comment events
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.

Verify a TikTok webhook in Python
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_age

Jak 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 a destination through MCP
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.

Set a destination with the Partner API
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 appeasyCoexistence to your endpoint
HeaderTiktok-Signature: t=<unix>,s=<hex>X-EC-Signature: t=<unix>,v1=<hex>
KeyThe developer app's secretThe account's signing secret, shown once
EventsVIDEO and COMMENT, per appcomment.update, per connected account
Bodyclient_key, event, create_time, user_openid, content as a stringplatform, account_id, external_id, entry with content parsed
RetriesUp to 72 hoursNone: one attempt, 8 seconds, no redirects

Jak to skonfigurować

  1. Grant the permissionsGive the developer app Business Content for publishing events and Business Comment for comment events, and have owners grant comment.list.
  2. Build the callbackServe an HTTPS endpoint that checks Tiktok-Signature and replies 200 before doing any work.
  3. Subscribe each event typeCall /business/webhook/update/ with app_id, secret, event_type and callback_url, once for VIDEO and once for COMMENT.
  4. Confirm the configurationCall /business/webhook/list/ for each event_type and check that the callback_url, and any item_list, came back.
  5. 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.
Z EasyCoexistence zrobisz to

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