Setting up TikTok API for Business webhooks
TikTok's API for Business sends webhooks to one callback URL per developer app and event type, set with POST /business/webhook/update/ using the app's app_id and secret. event_type VIDEO subscribes to the four post publishing events, and COMMENT to comment.update. Each delivery is an HTTPS POST signed in the Tiktok-Signature header with an HMAC-SHA256 keyed by the app secret.
easyCoexistence keeps TikTok's comment webhook subscribed for its app, checks TikTok's signature and passes each comment event for your account to your HTTPS endpoint, signed with a secret of its own.
How long TikTok retries a delivery not answered with HTTP 200, backing off exponentially, before discarding it.
Most post IDs one item_list can name to limit comment.update events to particular posts.
Current value of the webhook-schema-version header TikTok sends with each delivery.
What TikTok's reference lists for the webhook configuration endpoints, which authenticate with the app ID and secret.
Algorithm behind Tiktok-Signature: the timestamp, a dot and the body, keyed with the app secret and hex-encoded.
App permission under TikTok Accounts needed for comment.update; publishing events need Business Content.
Which webhook events can a TikTok account app receive?
Two categories, each subscribed as its own event_type. VIDEO covers posts published through /business/video/publish/ or /business/photo/publish/, and COMMENT covers comments on the account's photo posts and public video posts, whether they were published through the API or in the TikTok app:
What does the app need before subscribing?
Access to the API for Business, a developer app, and TikTok accounts that have authorized it. TikTok's subscription guide adds a permission for each category, and the comment event needs a scope from each owner:
- Publishing events: the TikTok Accounts, Business Content permission on the app.
- Comment events: the TikTok Accounts, Business Comment permission on the app.
- comment.update: the comment.list scope, granted by the owner and kept valid.
- A callback URL on HTTPS that answers HTTP 200 straight away.
How do you subscribe?
With a POST to /business/webhook/update/, once per event_type. The body takes app_id and secret, the event_type, VIDEO or COMMENT, and callback_url; for COMMENT it can also take item_list. The response echoes app_id, event_type, callback_url and, when one is configured, item_list. Calling it again for the same event_type replaces the 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" }
}How does item_list narrow comment events?
It limits comment.update to the posts it names, up to 100 IDs from /business/video/list/, and the first list decides the mode for the app from then on:
- First COMMENT call with
item_list: events arrive for the listed posts only. - Later calls with
item_list: the new posts join the ones already listed. - COMMENT call without
item_list, none set before: events arrive for the posts of the accounts that authorized the app. - COMMENT call without
item_list, once a list exists: the configured posts stay as they are.
How do you check or remove a subscription?
GET /business/webhook/list/ with app_id, secret and event_type returns the configuration: callback_url appears only when one exists for that event type, and item_list only when one was set. POST /business/webhook/delete/ with app_id, secret and event_type removes it; for COMMENT, an item_list in the delete call removes those posts only, and without one the comment events stop for all posts.
What must the callback URL do?
Answer at once. TikTok POSTs JSON over HTTPS and treats anything but an HTTP 200 as a failed delivery, retrying with exponential backoff for up to 72 hours before discarding the event. Delivery is at least once, so the same event can arrive twice and processing has to be idempotent. Each request carries three headers worth logging, tiktok-signature, webhook-schema-version and x-tt-logid, and a body of client_key, event, create_time in seconds, user_openid, which is the account's business_id, and content, a serialized JSON string.
How do you verify Tiktok-Signature?
Split the header, t=<unix>,s=<hex>, on commas and then on the equals sign. Build the signed message from the t value, a dot and the request body, compute an HMAC-SHA256 of it keyed with the app secret, hex-encode it and compare it with s. Then check how old t is: TikTok signs the delivery time to defeat replays, and its sample accepts a delay of 5 seconds. Working from the raw body as received avoids re-serializing the JSON differently.
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_ageHow do you receive TikTok events through easyCoexistence?
By giving the account a destination. easyCoexistence keeps its own app subscribed to COMMENT, checks TikTok's signature, answers TikTok at once, and POSTs each comment.update for a connected account to the HTTPS endpoint set for it. From Claude or ChatGPT, set_social_webhook_destination takes the account_id and a url, or null to stop, and returns a signing secret shown only once; calling it again issues a new one. Publishing events are not forwarded: get_tiktok_publish_status follows a post instead.
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. ..."
}How do you set it with the Partner API?
With PUT /channels/{id}/webhook on https://easycoexistence.com/api/v1, your ec_live_ key as a bearer token, and a body of {"url": "https://..."}. The answer holds webhook_url, signing_secret and a note, and {"url": null} stops forwarding. The URL has to use HTTPS on a public host; an unknown channel returns 404 not_found, a removed one 409 removed and a suspended one 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": "..." }How do the two deliveries differ?
A forward from easyCoexistence is signed and shaped differently from TikTok's own delivery, so a receiver written for one needs changes for the other. The forwarded payload keeps TikTok's comment fields, with content parsed and its IDs as strings; what changes is how each delivery is signed, scoped and retried:
| 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 |
How to set it up
- 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.
Common mistakes
- Processing the event before answering. TikTok asks for an immediate 200 and retries deliveries it does not see acknowledged, so queue the work and reply first.
- Sending item_list on the first COMMENT subscription by accident. From then on, TikTok reports comment events for the listed posts only.
- Verifying with the access token. TikTok signs webhooks with the app secret, the same one /business/webhook/update/ takes.
- Pointing two environments at one app. Each event type keeps one callback_url per app, and a new /business/webhook/update/ call replaces it.
Set it with set_social_webhook_destination from Claude or ChatGPT, or with PUT /channels/{id}/webhook. US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.
easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.
Frequently asked questions
Which headers does a TikTok webhook delivery carry?
tiktok-signature, webhook-schema-version, currently v1.0, and x-tt-logid, the delivery's ID. The JSON body holds client_key, event, create_time, user_openid and content.
Does TikTok send a webhook when a video is published?
Yes, with event_type VIDEO: post.publish.complete once TikTok has downloaded and checked the file, then post.publish.publicly_available, with the post_id, once the post is public.
How long does TikTok retry a failed webhook?
Up to 72 hours with exponential backoff, after which the event is discarded. Delivery is at least once, so expect duplicates.
Can I register my own callback on easyCoexistence's TikTok app?
No. The app's webhook settings stay with easyCoexistence. set_social_webhook_destination sends the account's comment events to you instead.
Keep reading
Connect your first channel in two minutes.
No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.
- 3 days free
- Cancel any time
- Official APIs only
- Monitored 24/7
Verified on