EntrarComeçar teste grátis
easyCoexistence APIs oficiais

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.

72 hours

Por quanto tempo a TikTok repete uma entrega não respondida com HTTP 200, com intervalo exponencial, antes de descartá-la.

100

Quantidade máxima de IDs de post que um item_list pode citar para limitar os eventos comment.update a determinados posts.

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 lista para os endpoints de configuração de webhook, que autenticam com o app ID e o secret.

HMAC-SHA256

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

Business Comment

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:

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

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

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

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 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 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 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.
Fazendo isso com o EasyCoexistence

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