Настройка вебхуков TikTok API for Business
TikTok API for Business отправляет вебхуки на один callback URL для каждого приложения разработчика и каждого типа события. Адрес задаётся запросом POST /business/webhook/update/ с app_id и секретом приложения. event_type VIDEO подписывает на четыре события публикации постов, COMMENT на comment.update. Каждая доставка представляет собой HTTPS POST, подписанный заголовком Tiktok-Signature: HMAC-SHA256 с ключом из секрета приложения.
easyCoexistence держит подписку TikTok на комментарии для своего приложения, проверяет подпись TikTok и передаёт каждое событие комментария для вашего аккаунта на ваш HTTPS-эндпоинт, подписанное собственным секретом.
Сколько времени TikTok повторяет доставку, на которую не получен ответ HTTP 200, с экспоненциальной задержкой, прежде чем отбросить её.
Наибольшее число ID постов, которое может указать один item_list, чтобы ограничить события comment.update отдельными постами.
Текущее значение заголовка webhook-schema-version, который TikTok отправляет с каждой доставкой.
Что в справочнике TikTok перечислено для эндпоинтов настройки вебхуков, которые аутентифицируются по app ID и секрету.
Алгоритм Tiktok-Signature: временная метка, точка и тело, подписанные секретом приложения и записанные в шестнадцатеричном виде.
Право приложения в разделе TikTok Accounts, нужное для comment.update; события публикации требуют Business Content.
Какие события вебхуков может получать приложение аккаунта TikTok?
Две категории, каждая подписывается отдельным event_type. VIDEO охватывает посты, опубликованные через /business/video/publish/ или /business/photo/publish/, а COMMENT охватывает комментарии к фото и публичным видео аккаунта, опубликованным через API или в приложении TikTok:
Что нужно приложению до подписки?
Доступ к API for Business, приложение разработчика и аккаунты TikTok, которые его авторизовали. Руководство TikTok по подписке добавляет разрешение для каждой категории, а событию комментариев нужна область доступа от каждого владельца:
- События публикации: разрешение TikTok Accounts, Business Content у приложения.
- События комментариев: разрешение TikTok Accounts, Business Comment у приложения.
- comment.update: область доступа comment.list, выданная владельцем и действующая.
- Адрес обратного вызова по HTTPS, который сразу отвечает HTTP 200.
Как оформить подписку?
Запросом POST на /business/webhook/update/, по одному на каждый event_type. В теле передаются app_id, секрет, event_type, VIDEO или COMMENT, и callback_url; для COMMENT можно также передать item_list. Ответ повторяет app_id, event_type, callback_url и, если он задан, item_list. Повторный вызов для того же event_type заменяет адрес обратного вызова.
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" }
}Как item_list сужает события комментариев?
Он ограничивает comment.update постами, которые перечислены в нём, до 100 ID из /business/video/list/, и первый список задаёт режим для приложения на всё дальнейшее время:
- Первый вызов COMMENT с
item_list: события приходят только по перечисленным постам. - Последующие вызовы с
item_list: новые посты добавляются к уже перечисленным. - Вызов COMMENT без
item_list, если список не задавался: события приходят по постам аккаунтов, которые авторизовали приложение. - Вызов COMMENT без
item_list, когда список уже есть: настроенные посты остаются без изменений.
Как проверить или удалить подписку?
GET /business/webhook/list/ с app_id, секретом и event_type возвращает конфигурацию: callback_url появляется, только если для этого типа события он есть, а item_list только если был задан. POST /business/webhook/delete/ с app_id, секретом и event_type удаляет подписку; для COMMENT item_list в запросе удаления убирает только указанные посты, а без него события комментариев прекращаются для всех постов.
Что должен делать адрес обратного вызова?
Отвечать сразу. TikTok отправляет JSON по HTTPS и считает любой ответ, кроме HTTP 200, неудачной доставкой, повторяя её с экспоненциальной задержкой до 72 часов, после чего событие отбрасывается. Доставка выполняется как минимум один раз, поэтому одно событие может прийти дважды, и обработка должна быть идемпотентной. Каждый запрос несёт три заголовка, которые стоит логировать: tiktok-signature, webhook-schema-version и x-tt-logid, а также тело с client_key, event, create_time в секундах, user_openid (это business_id аккаунта) и content, сериализованной строкой JSON.
Как проверить Tiktok-Signature?
Разбейте заголовок вида t=<unix>,s=<hex> сначала по запятым, затем по знаку равенства. Соберите подписываемое сообщение из значения t, точки и тела запроса, вычислите от него HMAC-SHA256 с ключом из секрета приложения, закодируйте в hex и сравните со значением s. Затем проверьте, насколько стар t: TikTok подписывает время доставки, чтобы защититься от повторов, а в его примере допускается задержка 5 секунд. Работа с исходным телом, как оно пришло, позволяет не пересериализовать 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_ageКак получать события TikTok через easyCoexistence?
Указав аккаунту адрес назначения. easyCoexistence держит собственное приложение подписанным на COMMENT, проверяет подпись TikTok, сразу отвечает TikTok и отправляет каждое comment.update для подключённого аккаунта на HTTPS-эндпоинт, заданный для него. Из Claude или ChatGPT set_social_webhook_destination принимает account_id и url, либо null, чтобы остановить пересылку, и возвращает секрет подписи, который показывается только один раз; повторный вызов выпускает новый. События публикации не пересылаются: вместо них get_tiktok_publish_status отслеживает пост.
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. ..."
}Как настроить через Partner API?
Запросом PUT /channels/{id}/webhook к https://easycoexistence.com/api/v1, с ключом ec_live_ как bearer-токеном и телом {"url": "https://..."}. В ответе есть webhook_url, signing_secret и note, а {"url": null} останавливает пересылку. URL должен использовать HTTPS на публичном хосте; неизвестный канал возвращает 404 not_found, удалённый 409 removed, приостановленный 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": "..." }Чем различаются две доставки?
Пересылка из easyCoexistence подписана и устроена иначе, чем собственная доставка TikTok, поэтому приёмник, написанный под одну, потребует изменений для другой. Пересылаемое тело сохраняет поля комментария TikTok, с разобранным content и ID в виде строк; меняется то, как каждая доставка подписывается, ограничивается и повторяется:
| 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 |
Как настроить
- 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.
Распространённые ошибки
- Обработка события до ответа. TikTok требует немедленного 200 и повторяет доставки, подтверждения которых не видит, поэтому поставьте работу в очередь и сначала ответьте.
- Случайная отправка item_list при первой подписке на COMMENT. С этого момента TikTok присылает события комментариев только по перечисленным постам.
- Проверка по токену доступа. TikTok подписывает вебхуки секретом приложения, тем же, что принимает /business/webhook/update/.
- Два окружения на одном приложении. Для каждого типа события приложение держит один callback_url, и новый вызов /business/webhook/update/ его заменяет.
Настройте через set_social_webhook_destination из Claude или ChatGPT либо через PUT /channels/{id}/webhook. От US$ 9 до US$ 0,75 за подключение в месяц, цена снижается по мере добавления подключений, с бесплатным пробным периодом в 3 дня.
Часто задаваемые вопросы
Какие заголовки несёт доставка вебхука TikTok?
tiktok-signature, webhook-schema-version, сейчас v1.0, и x-tt-logid, ID доставки. JSON-тело содержит client_key, event, create_time, user_openid и content.
Отправляет ли TikTok вебхук при публикации видео?
Да, с event_type VIDEO: post.publish.complete, когда TikTok загрузил и проверил файл, затем post.publish.publicly_available с post_id, когда пост стал публичным.
Как долго TikTok повторяет неудачный вебхук?
До 72 часов с экспоненциальной задержкой, после чего событие отбрасывается. Доставка выполняется как минимум один раз, поэтому ждите дубликатов.
Можно ли зарегистрировать свой callback в TikTok-приложении easyCoexistence?
Нет. Настройки вебхуков приложения остаются у easyCoexistence. set_social_webhook_destination вместо этого отправляет вам комментарии аккаунта.
Читайте дальше
Подключите первый канал за две минуты.
Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.
- 3 дня бесплатно
- Отмена в любой момент
- Только официальные API
- Мониторинг 24/7
Проверено по состоянию на