Webhooks van TikTok API for Business instellen
De API for Business van TikTok stuurt webhooks naar één callback-URL per ontwikkelaarsapp en gebeurtenistype, ingesteld via POST /business/webhook/update/, met het app_id en secret van de app. event_type VIDEO abonneert op de vier gebeurtenissen voor het publiceren van posts, en COMMENT op comment.update. Elke levering is een HTTPS-POST die ondertekend is in de header Tiktok-Signature, met een HMAC-SHA256 op basis van het secret van de app.
easyCoexistence houdt het commentwebhook van TikTok geabonneerd voor zijn app, controleert de handtekening van TikTok en stuurt elke commentgebeurtenis voor je account door naar je HTTPS-endpoint, ondertekend met een eigen secret.
Hoelang TikTok een levering opnieuw probeert als er geen HTTP 200 op komt, met exponentieel oplopende wachttijd, voordat die wordt weggegooid.
Het maximale aantal post-ID's dat één item_list kan noemen om comment.update-gebeurtenissen tot bepaalde posts te beperken.
De huidige waarde van de header webhook-schema-version die TikTok bij elke levering meestuurt.
Wat de referentie van TikTok vermeldt voor de endpoints voor de webhookconfiguratie, die authenticeren met de app-ID en het secret.
Het algoritme achter Tiktok-Signature: de timestamp, een punt en de body, gesleuteld met het secret van de app en hex-gecodeerd.
De app-rechten onder TikTok Accounts die nodig zijn voor comment.update; publicatiegebeurtenissen vragen Business Content.
Welke webhook-gebeurtenissen kan een app voor een TikTok-account ontvangen?
Twee categorieën, die elk als eigen event_type worden geabonneerd. VIDEO omvat posts die zijn gepubliceerd via /business/video/publish/ of /business/photo/publish/, en COMMENT omvat reacties op de fotoposts en openbare videoposts van het account, ongeacht of die via de API of in de TikTok-app zijn gepubliceerd:
Wat heeft de app nodig voor het abonneren?
Toegang tot de API for Business, een ontwikkelaarsapp en TikTok-accounts die die hebben geautoriseerd. De abonnementsgids van TikTok voegt per categorie een recht toe, en de commentgebeurtenis vraagt een scope van elke eigenaar:
- Publicatiegebeurtenissen: het recht TikTok Accounts, Business Content op de app.
- Commentgebeurtenissen: het recht TikTok Accounts, Business Comment op de app.
- comment.update: de scope comment.list, verleend door de eigenaar en geldig gehouden.
- Een callback-URL op HTTPS die meteen HTTP 200 antwoordt.
Hoe abonneer je?
Met een POST naar /business/webhook/update/, eenmaal per event_type. De body bevat app_id en secret, het event_type, VIDEO of COMMENT, en callback_url; bij COMMENT kan hij ook item_list bevatten. Het antwoord herhaalt app_id, event_type, callback_url en, als er een is ingesteld, item_list. Opnieuw aanroepen voor hetzelfde event_type vervangt de callback-URL.
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" }
}Hoe beperkt item_list commentgebeurtenissen?
Het beperkt comment.update tot de posts die erin staan, tot 100 ID's uit /business/video/list/, en de eerste lijst bepaalt daarna de modus voor de app:
- Eerste COMMENT-aanroep met
item_list: gebeurtenissen komen alleen voor de vermelde posts binnen. - Latere aanroepen met
item_list: de nieuwe posts voegen zich bij de al vermelde. - COMMENT-aanroep zonder
item_list, vooraf niets ingesteld: gebeurtenissen komen binnen voor de posts van de accounts die de app hebben geautoriseerd. - COMMENT-aanroep zonder
item_list, zodra er een lijst bestaat: de ingestelde posts blijven zoals ze zijn.
Hoe controleer of verwijder je een abonnement?
GET /business/webhook/list/ met app_id, secret en event_type geeft de configuratie terug: callback_url verschijnt alleen als er voor dat gebeurtenistype een bestaat, en item_list alleen als er een is ingesteld. POST /business/webhook/delete/ met app_id, secret en event_type verwijdert het; bij COMMENT verwijdert een item_list in de delete-aanroep alleen die posts, en zonder item_list stoppen de commentgebeurtenissen voor alle posts.
Wat moet de callback-URL doen?
Antwoord meteen. TikTok stuurt JSON via HTTPS en behandelt alles behalve een HTTP 200 als mislukte levering. Het probeert het met exponentieel oplopende wachttijd tot 72 uur lang opnieuw, voordat de gebeurtenis wordt weggegooid. Levering gebeurt minstens één keer, dus dezelfde gebeurtenis kan twee keer binnenkomen en de verwerking moet idempotent zijn. Elk verzoek bevat drie headers die het loggen waard zijn: tiktok-signature, webhook-schema-version en x-tt-logid, en een body met client_key, event, create_time in seconden, user_openid, dat het business_id van het account is, en content, een geserialiseerde JSON-string.
Hoe verifieer je Tiktok-Signature?
Splits de header t=<unix>,s=<hex> op komma's en daarna op het gelijkteken. Stel het ondertekende bericht samen uit de waarde van t, een punt en de body van het verzoek. Bereken daarvan een HMAC-SHA256, gesleuteld met het secret van de app, codeer die hex en vergelijk die met s. Controleer daarna hoe oud t is: TikTok ondertekent het tijdstip van levering om herhaalaanvallen tegen te gaan, en de voorbeeldcode van TikTok aanvaardt een vertraging van 5 seconden. Werk vanuit de ruwe body zoals ontvangen; dan serialiseer je de JSON niet opnieuw op een andere manier.
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_ageHoe ontvang je TikTok-gebeurtenissen via easyCoexistence?
Door het account een bestemming te geven. easyCoexistence houdt zijn eigen app geabonneerd op COMMENT, controleert de handtekening van TikTok, antwoordt TikTok meteen en stuurt elke comment.update voor een verbonden account via POST door naar het HTTPS-endpoint dat ervoor is ingesteld. Vanuit Claude of ChatGPT neemt set_social_webhook_destination de account_id en een url, of null om te stoppen, en geeft een ondertekeningssecret terug dat je maar één keer ziet; opnieuw aanroepen geeft een nieuw secret uit. Publicatiegebeurtenissen worden niet doorgestuurd: get_tiktok_publish_status volgt een post in plaats daarvan.
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. ..."
}Hoe stel je het in met de Partner API?
Met PUT /channels/{id}/webhook op https://easycoexistence.com/api/v1, je ec_live_-sleutel als bearer token en een body van {"url": "https://..."}. Het antwoord bevat webhook_url, signing_secret en een opmerking, en {"url": null} stopt het doorsturen. De URL moet HTTPS gebruiken op een publieke host; een onbekend kanaal geeft 404 not_found, een verwijderd kanaal 409 removed en een geschorst kanaal 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": "..." }Hoe verschillen de twee leveringen?
Een doorgestuurde levering van easyCoexistence is anders ondertekend en gevormd dan die van TikTok zelf, dus een ontvanger die voor de ene is geschreven, heeft aanpassingen nodig voor de andere. De doorgestuurde payload behoudt de commentvelden van TikTok, met content geparsed en de ID's als strings; wat verandert is hoe elke levering wordt ondertekend, afgebakend en opnieuw geprobeerd:
| 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 |
Zo stel je het in
- 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.
Veelgemaakte fouten
- Verwerken voordat je antwoordt. TikTok vraagt om een direct 200 en probeert leveringen opnieuw die het niet bevestigd ziet, dus zet het werk in de wachtrij en antwoord eerst.
- Per ongeluk item_list meesturen bij het eerste COMMENT-abonnement. Vanaf dan meldt TikTok commentgebeurtenissen alleen voor de vermelde posts.
- Verifiëren met het access token. TikTok ondertekent webhooks met het secret van de app, hetzelfde dat /business/webhook/update/ aanneemt.
- Twee omgevingen op één app laten wijzen. Elk gebeurtenistype houdt één callback_url per app, en een nieuwe aanroep van /business/webhook/update/ vervangt die.
Stel het in met set_social_webhook_destination vanuit Claude of ChatGPT, of met PUT /channels/{id}/webhook. US$ 9 tot US$ 0,75 per verbinding per maand, dalend naarmate je verbindingen toevoegt, met de eerste 3 dagen gratis.
Veelgestelde vragen
Welke headers bevat een TikTok-webhooklevering?
tiktok-signature, webhook-schema-version, momenteel v1.0, en x-tt-logid, de ID van de levering. De JSON-body bevat client_key, event, create_time, user_openid en content.
Stuurt TikTok een webhook als een video is gepubliceerd?
Ja, met event_type VIDEO: post.publish.complete zodra TikTok het bestand heeft gedownload en gecontroleerd, daarna post.publish.publicly_available, met de post_id, zodra de post openbaar is.
Hoelang probeert TikTok een mislukte webhook opnieuw?
Tot 72 uur met exponentieel oplopende wachttijd, daarna wordt de gebeurtenis weggegooid. Levering gebeurt minstens één keer, dus reken op duplicaten.
Kan ik mijn eigen callback registreren op de TikTok-app van easyCoexistence?
Nee. De webhookinstellingen van de app blijven bij easyCoexistence. set_social_webhook_destination stuurt de commentgebeurtenissen van het account in plaats daarvan naar jou.
Lees verder
Koppel je eerste kanaal in twee minuten.
Geen platformbeoordelingen om op te wachten. Verbind WhatsApp, Instagram, TikTok of een ander kanaal, vraag je AI om te posten, te reageren of een rapport te maken, en zie het aan het werk.
- 3 dagen gratis
- Op elk moment opzegbaar
- Alleen officiële API's
- 24/7 bewaakt
Geverifieerd op