Configurando webhooks da TikTok API for Business
A API for Business da TikTok envia webhooks para uma URL de callback por app de desenvolvedor e tipo de evento, definida com POST /business/webhook/update/ usando o app_id e o secret do app. O event_type VIDEO inscreve nos quatro eventos de publicação de post, e COMMENT em comment.update. Cada entrega é um POST HTTPS assinado no cabeçalho Tiktok-Signature com HMAC-SHA256, usando o app secret como chave.
O easyCoexistence mantém o webhook de comentários da TikTok inscrito para o seu app, verifica a assinatura da TikTok e repassa cada evento de comentário da sua conta para o seu endpoint HTTPS, assinado com um segredo próprio.
Por quanto tempo a TikTok repete uma entrega não respondida com HTTP 200, com intervalo exponencial, antes de descartá-la.
Quantidade máxima de IDs de post que um item_list pode citar para limitar os eventos comment.update a determinados posts.
Valor atual do cabeçalho webhook-schema-version que a TikTok envia em cada entrega.
O que a referência da TikTok lista para os endpoints de configuração de webhook, que autenticam com o app ID e o secret.
Algoritmo por trás do Tiktok-Signature: o timestamp, um ponto e o corpo, com chave no app secret e codificado em hexadecimal.
Permissão do app em TikTok Accounts necessária para comment.update; eventos de publicação exigem Business Content.
Quais eventos de webhook um app de conta TikTok pode receber?
Duas categorias, cada uma inscrita com seu próprio event_type. VIDEO cobre posts publicados por /business/video/publish/ ou /business/photo/publish/, e COMMENT cobre comentários nos posts de foto da conta e nos vídeos públicos, tenham sido publicados pela API ou pelo app da TikTok:
O que o app precisa antes de se inscrever?
Acesso à API for Business, um app de desenvolvedor e contas TikTok que o tenham autorizado. O guia de inscrição da TikTok acrescenta uma permissão para cada categoria, e o evento de comentário exige um escopo de cada proprietário:
- Eventos de publicação: a permissão TikTok Accounts, Business Content no app.
- Eventos de comentário: a permissão TikTok Accounts, Business Comment no app.
- comment.update: o escopo comment.list, concedido pelo proprietário e mantido válido.
- Uma URL de callback em HTTPS que responda HTTP 200 imediatamente.
Como se inscrever?
Com um POST para /business/webhook/update/, uma vez por event_type. O corpo recebe app_id e secret, o event_type, VIDEO ou COMMENT, e callback_url; para COMMENT também pode receber item_list. A resposta repete app_id, event_type, callback_url e, quando configurado, item_list. Chamar de novo para o mesmo event_type substitui a URL de callback.
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 o item_list restringe os eventos de comentário?
Ele limita comment.update aos posts citados, até 100 IDs de /business/video/list/, e a primeira lista define o modo do app dali em diante:
- Primeira chamada COMMENT com
item_list: os eventos chegam só dos posts listados. - Chamadas seguintes com
item_list: os novos posts se somam aos já listados. - Chamada COMMENT sem
item_list, nenhuma definida antes: os eventos chegam dos posts das contas que autorizaram o app. - Chamada COMMENT sem
item_list, com uma lista já existente: os posts configurados permanecem como estão.
Como verificar ou remover uma inscrição?
GET /business/webhook/list/ com app_id, secret e event_type retorna a configuração: callback_url aparece só quando existe uma para aquele tipo de evento, e item_list só quando foi definido. POST /business/webhook/delete/ com app_id, secret e event_type a remove; para COMMENT, um item_list na chamada de remoção retira apenas esses posts, e sem ele os eventos de comentário param para todos os posts.
O que a URL de callback precisa fazer?
Responder de imediato. A TikTok faz POST de JSON por HTTPS e trata qualquer resposta diferente de HTTP 200 como entrega falha, repetindo com intervalo exponencial por até 72 horas antes de descartar o evento. A entrega é pelo menos uma vez, então o mesmo evento pode chegar duas vezes e o processamento precisa ser idempotente. Cada requisição traz três cabeçalhos que vale registrar: 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 verificar o Tiktok-Signature?
Divida o cabeçalho, t=<unix>,s=<hex>, por vírgulas e depois pelo sinal de igual. Monte a mensagem assinada com o valor de t, um ponto e o corpo da requisição, calcule o HMAC-SHA256 dela com a chave do app secret, codifique em hexadecimal e compare com s. Depois verifique a idade de t: a TikTok assina o horário da entrega para impedir ataques de replay, e o exemplo dela aceita um atraso de 5 segundos. Trabalhar com o corpo bruto como recebido evita reserializar o JSON de forma diferente.
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_ageComo receber eventos da TikTok pelo easyCoexistence?
Dando um destino à conta. O easyCoexistence mantém o próprio app inscrito em COMMENT, verifica a assinatura da TikTok, responde a ela de imediato e faz POST de cada comment.update de uma conta conectada para o endpoint HTTPS definido para ela. Pelo Claude ou pelo ChatGPT, set_social_webhook_destination recebe account_id e url, ou null para parar, e retorna um segredo de assinatura mostrado apenas uma vez; chamá-lo de novo emite um novo. Eventos de publicação não são encaminhados: get_tiktok_publish_status acompanha o post.
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 configurar pela Partner API?
Com PUT /channels/{id}/webhook em https://easycoexistence.com/api/v1, sua chave ec_live_ como bearer token e um corpo {"url": "https://..."}. A resposta traz webhook_url, signing_secret e uma note, e {"url": null} para o encaminhamento. A URL precisa usar HTTPS em um host público; um canal desconhecido retorna 404 not_found, um removido 409 removed e um suspenso 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": "..." }Em que diferem as duas entregas?
Um encaminhamento do easyCoexistence é assinado e estruturado de forma diferente da entrega própria da TikTok, então um receptor escrito para uma precisa de ajustes para a outra. O payload encaminhado mantém os campos de comentário da TikTok, com content interpretado e os IDs como strings; o que muda é como cada entrega é assinada, delimitada e repetida:
| 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 |
Como configurar
- 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.
Erros comuns
- Processar o evento antes de responder. A TikTok pede um 200 imediato e repete entregas que não vê confirmadas, então enfileire o trabalho e responda primeiro.
- Enviar item_list na primeira inscrição COMMENT por engano. Dali em diante, a TikTok informa eventos de comentário só dos posts listados.
- Verificar com o access token. A TikTok assina os webhooks com o app secret, o mesmo que /business/webhook/update/ recebe.
- Apontar dois ambientes para um mesmo app. Cada tipo de evento mantém uma callback_url por app, e uma nova chamada a /business/webhook/update/ a substitui.
Configure com set_social_webhook_destination pelo Claude ou pelo ChatGPT, ou com PUT /channels/{id}/webhook. De US$ 9 a US$ 0.75 por conexão por mês, caindo conforme você adiciona conexões, com os primeiros 3 dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
Quais cabeçalhos uma entrega de webhook da TikTok traz?
tiktok-signature, webhook-schema-version, atualmente v1.0, e x-tt-logid, o ID da entrega. O corpo JSON traz 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 baixa e verifica o arquivo, depois post.publish.publicly_available, com o post_id, quando o post fica público.
Por quanto tempo a TikTok repete um webhook que falhou?
Até 72 horas com intervalo exponencial, depois do que o evento é descartado. A entrega é pelo menos uma vez, então espere duplicatas.
Posso registrar minha própria URL de callback no app da TikTok do easyCoexistence?
Não. As configurações de webhook do app ficam com o easyCoexistence. set_social_webhook_destination envia os eventos de comentário da conta para você.
Continue lendo
Conecte seu primeiro canal em dois minutos.
Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorado 24/7
Verificado em