ВойтиНачать бесплатный пробный период
easyCoexistence Официальные API

Настройка вебхуков 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-эндпоинт, подписанное собственным секретом.

72 hours

Сколько времени TikTok повторяет доставку, на которую не получен ответ HTTP 200, с экспоненциальной задержкой, прежде чем отбросить её.

100

Наибольшее число ID постов, которое может указать один item_list, чтобы ограничить события comment.update отдельными постами.

v1.0

Текущее значение заголовка webhook-schema-version, который TikTok отправляет с каждой доставкой.

No permission

Что в справочнике TikTok перечислено для эндпоинтов настройки вебхуков, которые аутентифицируются по app ID и секрету.

HMAC-SHA256

Алгоритм Tiktok-Signature: временная метка, точка и тело, подписанные секретом приложения и записанные в шестнадцатеричном виде.

Business Comment

Право приложения в разделе TikTok Accounts, нужное для comment.update; события публикации требуют Business Content.

Какие события вебхуков может получать приложение аккаунта TikTok?

Две категории, каждая подписывается отдельным event_type. VIDEO охватывает посты, опубликованные через /business/video/publish/ или /business/photo/publish/, а COMMENT охватывает комментарии к фото и публичным видео аккаунта, опубликованным через API или в приложении 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

Что нужно приложению до подписки?

Доступ к 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 заменяет адрес обратного вызова.

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" }
}

Как 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 иначе.

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

Как получать события TikTok через easyCoexistence?

Указав аккаунту адрес назначения. easyCoexistence держит собственное приложение подписанным на COMMENT, проверяет подпись TikTok, сразу отвечает TikTok и отправляет каждое comment.update для подключённого аккаунта на HTTPS-эндпоинт, заданный для него. Из Claude или ChatGPT set_social_webhook_destination принимает account_id и url, либо null, чтобы остановить пересылку, и возвращает секрет подписи, который показывается только один раз; повторный вызов выпускает новый. События публикации не пересылаются: вместо них get_tiktok_publish_status отслеживает пост.

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. ..."
}

Как настроить через 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.

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": "..." }

Чем различаются две доставки?

Пересылка из easyCoexistence подписана и устроена иначе, чем собственная доставка TikTok, поэтому приёмник, написанный под одну, потребует изменений для другой. Пересылаемое тело сохраняет поля комментария TikTok, с разобранным content и ID в виде строк; меняется то, как каждая доставка подписывается, ограничивается и повторяется:

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

Как настроить

  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.

Распространённые ошибки

  • Обработка события до ответа. TikTok требует немедленного 200 и повторяет доставки, подтверждения которых не видит, поэтому поставьте работу в очередь и сначала ответьте.
  • Случайная отправка item_list при первой подписке на COMMENT. С этого момента TikTok присылает события комментариев только по перечисленным постам.
  • Проверка по токену доступа. TikTok подписывает вебхуки секретом приложения, тем же, что принимает /business/webhook/update/.
  • Два окружения на одном приложении. Для каждого типа события приложение держит один callback_url, и новый вызов /business/webhook/update/ его заменяет.
Настройка с EasyCoexistence

Настройте через 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 вместо этого отправляет вам комментарии аккаунта.

Читайте дальше

События вебхука комментариев TikTokКак вебхук comment.update от TikTok сообщает о комментариях и ответах, что несёт каждое событие и как оно приходит на ваш эндпоинт с подписью.Токены доступа TikTok API for Business: 24 часа, обновление и отзывКак TikTok API for Business выдаёт токены аккаунта: обмен auth_code, токен доступа на 24 часа, токен обновления на год, обновление и отзыв.Scope в TikTok API for Business: что открывает каждое разрешениеРазрешения API TikTok Accounts по именам TikTok: что открывает каждое, scope токена для полей и как проверить токен.Как опубликовать видео в TikTok через APIПубликуйте видео в TikTok через API for Business: эндпоинт публикации, тело JSON, share_id из ответа и проверка статуса в curl и Python.Ответы на комментарии TikTok и модерация через APIКак API TikTok для бизнеса читает и скрывает комментарии, отвечает на них и удаляет свои, а правила по ключевым словам отвечают на новые сами.Как проверить статус публикации поста TikTok через APIКак отслеживать пост TikTok, опубликованный через API: share_id, статусы PROCESSING_DOWNLOAD, PUBLISH_COMPLETE и FAILED, ID постов и причины сбоя.

Подключите первый канал за две минуты.

Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.

  • 3 дня бесплатно
  • Отмена в любой момент
  • Только официальные API
  • Мониторинг 24/7

Проверено по состоянию на