Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

Configurar webhooks da TikTok API for Business

A API for Business da TikTok envia webhooks para um único URL de callback por aplicação de programador e por tipo de evento, definido com POST /business/webhook/update/ usando o app_id e o secret da aplicação. O event_type VIDEO subscreve os quatro eventos de publicação de publicações, e COMMENT subscreve o comment.update. Cada entrega é um POST HTTPS assinado no cabeçalho Tiktok-Signature, com um HMAC-SHA256 cuja chave é o secret da aplicação.

A easyCoexistence mantém a subscrição de webhooks de comentários da TikTok para a sua aplicação, verifica a assinatura da TikTok e entrega cada evento de comentário da sua conta ao seu endpoint HTTPS, assinado com um segredo próprio.

72 hours

Quanto tempo a TikTok repete uma entrega sem resposta HTTP 200, com recuo exponencial, antes de a descartar.

100

O número máximo de IDs de publicações que um item_list pode indicar para limitar os eventos comment.update a publicações concretas.

v1.0

Valor atual do cabeçalho webhook-schema-version que a TikTok envia em cada entrega.

No permission

O que a referência da TikTok indica para os endpoints de configuração de webhooks, que autenticam com o app ID e o secret da aplicação.

HMAC-SHA256

Algoritmo por trás do Tiktok-Signature: o timestamp, um ponto e o corpo, com chave no secret da aplicação e codificado em hexadecimal.

Business Comment

Permissão da aplicação em TikTok Accounts necessária para comment.update; os eventos de publicação exigem Business Content.

Que eventos de webhook pode uma aplicação de conta TikTok receber?

Duas categorias, subscritas cada uma como o seu próprio event_type. VIDEO abrange as publicações feitas através de /business/video/publish/ ou /business/photo/publish/, e COMMENT abrange os comentários nas publicações de fotografia da conta e nos vídeos públicos, quer tenham sido publicados pela API quer na aplicação 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

O que a aplicação precisa antes de subscrever?

Acesso à API for Business, uma aplicação de programador e contas TikTok que a tenham autorizado. O guia de subscrição da TikTok acrescenta uma permissão para cada categoria, e o evento de comentários precisa de um âmbito de cada proprietário:

  • Eventos de publicação: a permissão TikTok Accounts, Business Content na aplicação.
  • Eventos de comentários: a permissão TikTok Accounts, Business Comment na aplicação.
  • comment.update: o âmbito comment.list, concedido pelo proprietário e mantido válido.
  • Um URL de callback em HTTPS que responda HTTP 200 de imediato.

Como se subscreve?

Com um POST para /business/webhook/update/, uma vez por cada event_type. O corpo aceita app_id e secret, o event_type, VIDEO ou COMMENT, e callback_url; para COMMENT pode aceitar também item_list. A resposta repete app_id, event_type, callback_url e, quando estiver configurado, item_list. Voltar a chamar para o mesmo event_type substitui o URL de callback.

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

Como é que o item_list limita os eventos de comentários?

Limita o comment.update às publicações que indica, até 100 IDs de /business/video/list/, e a primeira lista define o modo da aplicação a partir de então:

  • Primeira chamada COMMENT com item_list: os eventos chegam apenas das publicações indicadas.
  • Chamadas seguintes com item_list: as novas publicações juntam-se às que já estão na lista.
  • Chamada COMMENT sem item_list, nenhuma definida antes: os eventos chegam das publicações das contas que autorizaram a aplicação.
  • Chamada COMMENT sem item_list, depois de existir uma lista: as publicações configuradas mantêm-se como estão.

Como se verifica ou remove uma subscrição?

GET /business/webhook/list/ com app_id, secret e event_type devolve a configuração: callback_url só aparece quando existe para esse tipo de evento, e item_list só quando foi definido. POST /business/webhook/delete/ com app_id, secret e event_type remove-a; para COMMENT, um item_list no pedido de remoção retira apenas essas publicações, e sem ele os eventos de comentários deixam de chegar para todas as publicações.

O que deve fazer o URL de callback?

Responder de imediato. A TikTok faz POST de JSON por HTTPS e trata qualquer resposta diferente de HTTP 200 como entrega falhada, repetindo com recuo exponencial até 72 horas antes de descartar o evento. A entrega é pelo menos uma vez, por isso o mesmo evento pode chegar duas vezes e o processamento tem de ser idempotente. Cada pedido traz três cabeçalhos que vale a pena registar: tiktok-signature, webhook-schema-version e x-tt-logid, e um corpo com client_key, event, create_time em segundos, user_openid, que é o business_id da conta, e content, uma string JSON serializada.

Como se verifica o Tiktok-Signature?

Separe o cabeçalho, t=<unix>,s=<hex>, por vírgulas e depois pelo sinal de igual. Construa a mensagem assinada com o valor de t, um ponto e o corpo do pedido, calcule um HMAC-SHA256 dessa mensagem com chave no secret da aplicação, codifique-o em hexadecimal e compare-o com s. Depois verifique a idade de t: a TikTok assina a hora da entrega para impedir ataques de repetição, e o seu exemplo aceita um atraso de 5 segundos. Trabalhar a partir do corpo bruto tal como foi recebido evita reserializar o JSON de forma diferente.

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

Como recebe eventos da TikTok através da easyCoexistence?

Ao dar um destino à conta. A easyCoexistence mantém a sua própria aplicação subscrita a COMMENT, verifica a assinatura da TikTok, responde à TikTok de imediato e envia por POST cada comment.update de uma conta ligada para o endpoint HTTPS definido para ela. A partir do Claude ou do ChatGPT, set_social_webhook_destination recebe o account_id e um url, ou null para parar, e devolve um segredo de assinatura mostrado apenas uma vez; voltar a chamá-la emite um novo. Os eventos de publicação não são encaminhados: get_tiktok_publish_status acompanha a publicação em vez disso.

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

Como se configura com a Partner API?

Com PUT /channels/{id}/webhook em https://easycoexistence.com/api/v1, a chave ec_live_ como bearer token e um corpo {"url": "https://..."}. A resposta inclui webhook_url, signing_secret e uma nota, e {"url": null} interrompe o reencaminhamento. O URL tem de usar HTTPS num host público; um canal desconhecido devolve 404 not_found, um canal removido 409 removed e um canal suspenso 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": "..." }

Em que diferem as duas entregas?

Um reencaminhamento da easyCoexistence é assinado e estruturado de forma diferente da entrega própria da TikTok, por isso um recetor escrito para uma precisa de alterações para a outra. O payload reencaminhado mantém os campos de comentário da TikTok, com content analisado e os IDs como strings; o que muda é a forma como cada entrega é assinada, limitada e repetida:

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

Como configurar

  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.

Erros comuns

  • Processar o evento antes de responder. A TikTok pede um 200 imediato e repete as entregas que não vê confirmadas, por isso coloque o trabalho em fila e responda primeiro.
  • Enviar item_list na primeira subscrição COMMENT por acidente. A partir daí, a TikTok comunica os eventos de comentários apenas para as publicações indicadas.
  • Verificar com o token de acesso. A TikTok assina os webhooks com o secret da aplicação, o mesmo que /business/webhook/update/ recebe.
  • Apontar dois ambientes para uma só aplicação. Cada tipo de evento mantém um callback_url por aplicação, e uma nova chamada a /business/webhook/update/ substitui-o.
Fazer isto com a EasyCoexistence

Configure-o com set_social_webhook_destination a partir do Claude ou do ChatGPT, ou com PUT /channels/{id}/webhook. De US$ 9 a US$ 0.75 por ligação por mês, descendo à medida que acrescenta ligações, com os primeiros 3 dias gratuitos.

Perguntas frequentes

Que cabeçalhos traz uma entrega de webhook da TikTok?

tiktok-signature, webhook-schema-version, atualmente v1.0, e x-tt-logid, o ID da entrega. O corpo JSON contém client_key, event, create_time, user_openid e content.

A TikTok envia um webhook quando um vídeo é publicado?

Sim, com event_type VIDEO: post.publish.complete assim que a TikTok tiver transferido e verificado o ficheiro, e depois post.publish.publicly_available, com o post_id, quando a publicação ficar pública.

Quanto tempo repete a TikTok um webhook que falhou?

Até 72 horas com recuo exponencial, após o que o evento é descartado. A entrega é pelo menos uma vez, por isso esteja preparado para duplicados.

Posso configurar o meu próprio callback na aplicação TikTok da easyCoexistence?

Não. As definições de webhook da aplicação ficam com a easyCoexistence. set_social_webhook_destination envia-lhe, em vez disso, os eventos de comentários da conta.

Continue a ler

Ligue o seu primeiro canal em dois minutos.

Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.

  • 3 dias grátis
  • Cancele quando quiser
  • Só APIs oficiais
  • Monitorizado 24/7

Verificado em