Configurarea webhook-urilor din TikTok API for Business
API for Business al TikTok trimite webhook-uri către o singură adresă de callback pentru fiecare aplicație de dezvoltator și tip de eveniment, setată printr-un POST la /business/webhook/update/, folosind app_id și secretul aplicației. event_type VIDEO abonează la cele patru evenimente de publicare a postărilor, iar COMMENT la comment.update. Fiecare livrare este un POST HTTPS semnat în antetul Tiktok-Signature, cu un HMAC-SHA256 calculat cu secretul aplicației.
easyCoexistence menține abonat la comentariile TikTok aplicația sa, verifică semnătura TikTok și transmite fiecare eveniment de comentariu pentru contul dumneavoastră către endpoint-ul dumneavoastră HTTPS, semnat cu un secret propriu.
Cât timp reîncearcă TikTok o livrare la care nu s-a primit răspuns HTTP 200, cu întârzieri exponențiale, înainte să o arunce.
Cele mai multe ID-uri de postări pe care le poate numi un singur item_list pentru a limita evenimentele comment.update la anumite postări.
Valoarea actuală a antetului webhook-schema-version pe care TikTok îl trimite cu fiecare livrare.
Ce enumeră referința TikTok pentru endpoint-urile de configurare a webhook-urilor, care se autentifică cu ID-ul și secretul aplicației.
Algoritmul din spatele Tiktok-Signature: marca de timp, un punct și corpul cererii, calculate cu secretul aplicației și codificate hexazecimal.
Permisiunea aplicației din TikTok Accounts necesară pentru comment.update; evenimentele de publicare necesită Business Content.
Ce evenimente webhook poate primi o aplicație pentru un cont TikTok?
Două categorii, fiecare abonată ca propriul event_type. VIDEO acoperă postările publicate prin /business/video/publish/ sau /business/photo/publish/, iar COMMENT acoperă comentariile de la postările foto ale contului și de la postările video publice, indiferent dacă au fost publicate prin API sau în aplicația TikTok:
Ce are nevoie aplicația înainte de abonare?
Acces la API for Business, o aplicație de dezvoltator și conturi TikTok care au autorizat-o. Ghidul de abonare al TikTok adaugă o permisiune pentru fiecare categorie, iar evenimentul de comentarii necesită un scope de la fiecare proprietar:
- Evenimente de publicare: permisiunea TikTok Accounts, Business Content pe aplicație.
- Evenimente de comentarii: permisiunea TikTok Accounts, Business Comment pe aplicație.
- comment.update: scope-ul comment.list, acordat de proprietar și menținut valid.
- Un URL de callback pe HTTPS care răspunde imediat cu HTTP 200.
Cum vă abonați?
Printr-un POST la /business/webhook/update/, o dată pentru fiecare event_type. Corpul cererii conține app_id și secret, event_type, VIDEO sau COMMENT, și callback_url; pentru COMMENT poate conține și item_list. Răspunsul reia app_id, event_type, callback_url și, dacă este configurat, item_list. Apelarea din nou pentru același event_type înlocuiește URL-ul de callback.
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" }
}Cum restrânge item_list evenimentele de comentarii?
Limitează comment.update la postările pe care le numește, până la 100 de ID-uri din /business/video/list/, iar prima listă decide modul aplicației de atunci încolo:
- Primul apel COMMENT cu
item_list: evenimentele sosesc doar pentru postările listate. - Apelurile ulterioare cu
item_list: postările noi se adaugă celor deja listate. - Apel COMMENT fără
item_list, dacă nu a fost setat nimic înainte: evenimentele sosesc pentru postările conturilor care au autorizat aplicația. - Apel COMMENT fără
item_list, odată ce există o listă: postările configurate rămân neschimbate.
Cum verificați sau eliminați un abonament?
GET /business/webhook/list/ cu app_id, secret și event_type returnează configurația: callback_url apare doar dacă există unul pentru tipul respectiv de eveniment, iar item_list doar dacă a fost setat. POST /business/webhook/delete/ cu app_id, secret și event_type îl elimină; pentru COMMENT, un item_list în apelul de ștergere elimină doar acele postări, iar fără el evenimentele de comentarii se opresc pentru toate postările.
Ce trebuie să facă URL-ul de callback?
Să răspundă imediat. TikTok trimite JSON prin HTTPS și consideră orice în afară de HTTP 200 o livrare eșuată, reîncercând cu întârziere exponențială timp de până la 72 de ore înainte să arunce evenimentul. Livrarea este cel puțin o dată, deci același eveniment poate sosi de două ori, iar procesarea trebuie să fie idempotentă. Fiecare cerere poartă trei antete utile de păstrat în jurnale: tiktok-signature, webhook-schema-version și x-tt-logid, și un corp cu client_key, event, create_time în secunde, user_openid, care este business_id-ul contului, și content, un șir JSON serializat.
Cum verificați Tiktok-Signature?
Împărțiți antetul, t=<unix>,s=<hex>, după virgule și apoi după semnul egal. Construiți mesajul semnat din valoarea lui t, un punct și corpul cererii, calculați un HMAC-SHA256 al acestuia cu secretul aplicației, codificați-l hexazecimal și comparați-l cu s. Apoi verificați cât de vechi este t: TikTok semnează momentul livrării pentru a împiedica reluările, iar exemplul său acceptă o întârziere de 5 secunde. Lucrând cu corpul brut, așa cum a fost primit, nu se reserializează JSON-ul, ceea ce ar putea schimba semnătura.
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_ageCum primiți evenimentele TikTok prin easyCoexistence?
Dând contului o destinație. easyCoexistence își menține propria aplicație abonată la COMMENT, verifică semnătura TikTok, răspunde imediat TikTok și trimite fiecare comment.update pentru un cont conectat la endpoint-ul HTTPS setat pentru acesta. Din Claude sau ChatGPT, set_social_webhook_destination primește account_id și un url, sau null pentru oprire, și returnează un secret de semnare afișat o singură dată; un nou apel emite un secret nou. Evenimentele de publicare nu sunt redirecționate: get_tiktok_publish_status urmărește în schimb o postare.
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. ..."
}Cum îl setați cu Partner API?
Cu PUT /channels/{id}/webhook pe https://easycoexistence.com/api/v1, cheia ec_live_ drept token bearer și un corp {"url": "https://..."}. Răspunsul conține webhook_url, signing_secret și o notă, iar {"url": null} oprește redirecționarea. URL-ul trebuie să folosească HTTPS pe un host public; un canal necunoscut returnează 404 not_found, unul eliminat 409 removed, iar unul suspendat 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": "..." }Cum diferă cele două livrări?
O redirecționare din easyCoexistence este semnată și structurată altfel decât livrarea proprie TikTok, așa că un receptor scris pentru una are nevoie de modificări pentru cealaltă. Payload-ul redirecționat păstrează câmpurile de comentarii TikTok, cu content parsat și ID-urile ca șiruri; ce se schimbă este modul în care este semnată, delimitată și reîncercată fiecare livrare:
| 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 |
Cum să îl configurați
- 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.
Greșeli frecvente
- Procesarea evenimentului înainte de răspuns. TikTok cere un 200 imediat și reîncearcă livrările pe care nu le vede confirmate, deci puneți lucrul în coadă și răspundeți mai întâi.
- Trimiterea accidentală a item_list la primul abonament COMMENT. De atunci încolo, TikTok raportează evenimentele de comentarii doar pentru postările listate.
- Verificarea cu token-ul de acces. TikTok semnează webhook-urile cu secretul aplicației, același pe care îl primește /business/webhook/update/.
- Direcționarea a două medii spre aceeași aplicație. Fiecare tip de eveniment păstrează un singur callback_url pe aplicație, iar un nou apel /business/webhook/update/ îl înlocuiește.
Setați-l cu set_social_webhook_destination din Claude sau ChatGPT, sau cu PUT /channels/{id}/webhook. De la US$ 9 până la US$ 0,75 pe conexiune pe lună, scăzând pe măsură ce adăugați conexiuni, cu primele 3 zile gratuite.
Întrebări frecvente
Ce antete transportă o livrare webhook TikTok?
tiktok-signature, webhook-schema-version, în prezent v1.0, și x-tt-logid, ID-ul livrării. Corpul JSON conține client_key, event, create_time, user_openid și content.
Trimite TikTok un webhook când un video este publicat?
Da, cu event_type VIDEO: post.publish.complete după ce TikTok a descărcat și verificat fișierul, apoi post.publish.publicly_available, cu post_id, când postarea devine publică.
Cât timp reîncearcă TikTok un webhook eșuat?
Până la 72 de ore, cu întârziere exponențială, după care evenimentul este aruncat. Livrarea este cel puțin o dată, deci așteptați-vă la duplicate.
Pot înregistra propriul callback pe aplicația TikTok a easyCoexistence?
Nu. Setările webhook ale aplicației rămân la easyCoexistence. set_social_webhook_destination trimite în schimb evenimentele de comentarii ale contului către dumneavoastră.
Continuați să citiți
Conectați primul canal în două minute.
Fără recenzii de platformă de așteptat. Conectați WhatsApp, Instagram, TikTok sau alt canal, apoi cereți AI-ului să publice, să răspundă sau să raporteze și urmăriți-l cum lucrează.
- 3 zile gratuit
- Anulați oricând
- Doar API-uri oficiale
- Monitorizat 24/7
Verificat la