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.
Quanto tempo a TikTok repete uma entrega sem resposta HTTP 200, com recuo exponencial, antes de a descartar.
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.
Valor atual do cabeçalho webhook-schema-version que a TikTok envia em cada entrega.
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.
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.
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:
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.
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.
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 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_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.
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 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 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.
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