Configurar los webhooks de TikTok API for Business
La API for Business de TikTok envía webhooks a una única URL de callback por app y tipo de evento, que se configura con POST /business/webhook/update/ usando el app_id y el secreto de la app. event_type VIDEO se suscribe a los cuatro eventos de publicación de publicaciones, y COMMENT a comment.update. Cada entrega es un POST HTTPS firmado en el encabezado Tiktok-Signature con un HMAC-SHA256 cuya clave es el secreto de la app.
easyCoexistence mantiene suscrito a su app el webhook de comentarios de TikTok, verifica la firma de TikTok y pasa cada evento de comentario de tu cuenta a tu endpoint HTTPS, firmado con un secreto propio.
Cuánto tiempo reintenta TikTok una entrega que no recibe respuesta HTTP 200, con espera exponencial, antes de descartarla.
Número máximo de IDs de publicaciones que un item_list puede indicar para limitar los eventos comment.update a publicaciones concretas.
Valor actual del encabezado webhook-schema-version que TikTok envía con cada entrega.
Lo que la referencia de TikTok indica para los endpoints de configuración de webhooks, que se autentican con el app ID y el secreto.
Algoritmo de Tiktok-Signature: la marca de tiempo, un punto y el cuerpo, con clave del secreto de la app y codificado en hexadecimal.
Permiso de la app en TikTok Accounts necesario para comment.update; los eventos de publicación requieren Business Content.
¿Qué eventos de webhook puede recibir una app de cuenta de TikTok?
Dos categorías, cada una suscrita con su propio event_type. VIDEO cubre las publicaciones hechas mediante /business/video/publish/ o /business/photo/publish/, y COMMENT cubre los comentarios de las publicaciones de fotos de la cuenta y de los videos públicos, ya sea que se hayan publicado por la API o en la app de TikTok:
¿Qué necesita la app antes de suscribirse?
Acceso a la API for Business, una app de desarrollador y cuentas de TikTok que la hayan autorizado. La guía de suscripción de TikTok añade un permiso por cada categoría, y el evento de comentarios necesita un scope de cada propietario:
- Eventos de publicación: el permiso TikTok Accounts, Business Content en la app.
- Eventos de comentarios: el permiso TikTok Accounts, Business Comment en la app.
- comment.update: el scope comment.list, concedido por el propietario y mantenido válido.
- Una URL de callback en HTTPS que responda HTTP 200 de inmediato.
¿Cómo se suscribe?
Con un POST a /business/webhook/update/, una vez por cada event_type. El cuerpo recibe app_id y secret, el event_type, VIDEO o COMMENT, y callback_url; para COMMENT también puede recibir item_list. La respuesta repite app_id, event_type, callback_url y, si hay uno configurado, item_list. Volver a llamar con el mismo event_type reemplaza la 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" }
}¿Cómo limita item_list los eventos de comentarios?
Limita comment.update a las publicaciones que indica, hasta 100 IDs de /business/video/list/, y la primera lista define el modo de la app a partir de entonces:
- Primera llamada COMMENT con
item_list: los eventos llegan solo de las publicaciones indicadas. - Llamadas posteriores con
item_list: las nuevas publicaciones se suman a las que ya estaban en la lista. - Llamada COMMENT sin
item_list, si antes no había ninguna: los eventos llegan de las publicaciones de las cuentas que autorizaron la app. - Llamada COMMENT sin
item_list, una vez que existe una lista: las publicaciones configuradas se mantienen tal cual.
¿Cómo se comprueba o elimina una suscripción?
GET /business/webhook/list/ con app_id, secret y event_type devuelve la configuración: callback_url aparece solo si existe para ese tipo de evento, e item_list solo si se definió. POST /business/webhook/delete/ con app_id, secret y event_type la elimina; en COMMENT, un item_list en la llamada de borrado quita solo esas publicaciones, y sin él los eventos de comentarios se detienen para todas las publicaciones.
¿Qué debe hacer la URL de callback?
Responder de inmediato. TikTok envía JSON por HTTPS y trata cualquier respuesta distinta de HTTP 200 como una entrega fallida, reintentando con espera exponencial durante hasta 72 horas antes de descartar el evento. La entrega es al menos una vez, así que el mismo evento puede llegar dos veces y el procesamiento debe ser idempotente. Cada petición lleva tres encabezados que conviene registrar: tiktok-signature, webhook-schema-version y x-tt-logid, y un cuerpo con client_key, event, create_time en segundos, user_openid, que es el business_id de la cuenta, y content, una cadena JSON serializada.
¿Cómo se verifica Tiktok-Signature?
Dividir el encabezado, t=<unix>,s=<hex>, por las comas y después por el signo igual. Construir el mensaje firmado con el valor de t, un punto y el cuerpo de la petición; calcular un HMAC-SHA256 de ese mensaje con la clave del secreto de la app, codificarlo en hexadecimal y compararlo con s. Luego revisar la antigüedad de t: TikTok firma la hora de entrega para impedir reenvíos maliciosos, y su ejemplo acepta un retraso de 5 segundos. Trabajar con el cuerpo crudo tal como llega evita volver a serializar el JSON de forma distinta.
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¿Cómo se reciben los eventos de TikTok a través de easyCoexistence?
Asignando a la cuenta un destino. easyCoexistence mantiene su propia app suscrita a COMMENT, verifica la firma de TikTok, responde a TikTok de inmediato y envía cada comment.update de una cuenta conectada al endpoint HTTPS configurado para ella. Desde Claude o ChatGPT, set_social_webhook_destination recibe account_id y una url, o null para detener el envío, y devuelve un secreto de firma que se muestra una sola vez; volver a llamarla emite uno nuevo. Los eventos de publicación no se reenvían: get_tiktok_publish_status hace seguimiento de la publicación en su lugar.
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. ..."
}¿Cómo se configura con la Partner API?
Con PUT /channels/{id}/webhook en https://easycoexistence.com/api/v1, la clave ec_live_ como token bearer y un cuerpo de {"url": "https://..."}. La respuesta contiene webhook_url, signing_secret y una nota, y {"url": null} detiene el reenvío. La URL debe usar HTTPS en un host público; un canal desconocido devuelve 404 not_found, uno eliminado 409 removed y uno suspendido 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": "..." }¿En qué se diferencian las dos entregas?
Un reenvío desde easyCoexistence va firmado y tiene una forma distinta a la entrega original de TikTok, así que un receptor escrito para una necesita cambios para la otra. La carga reenviada conserva los campos de comentario de TikTok, con content ya parseado y sus IDs como cadenas; lo que cambia es cómo se firma, se limita y se reintenta cada entrega:
| 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 |
Cómo configurarlo
- 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.
Errores comunes
- Procesar el evento antes de responder. TikTok pide un 200 inmediato y reintenta las entregas que no ve confirmadas, así que encola el trabajo y responde primero.
- Enviar item_list en la primera suscripción COMMENT por error. Desde entonces, TikTok informa los eventos de comentarios solo de las publicaciones indicadas.
- Verificar con el token de acceso. TikTok firma los webhooks con el secreto de la app, el mismo que recibe /business/webhook/update/.
- Apuntar dos entornos a una misma app. Cada tipo de evento conserva una callback_url por app, y una nueva llamada a /business/webhook/update/ la reemplaza.
Configúralo con set_social_webhook_destination desde Claude o ChatGPT, o con PUT /channels/{id}/webhook. De US$ 9 a US$ 0.75 por conexión al mes, que bajan a medida que sumas conexiones, con los primeros 3 días gratis.
Preguntas frecuentes
¿Qué encabezados trae una entrega de webhook de TikTok?
tiktok-signature, webhook-schema-version, actualmente v1.0, y x-tt-logid, el ID de la entrega. El cuerpo JSON contiene client_key, event, create_time, user_openid y content.
¿TikTok envía un webhook cuando se publica un video?
Sí, con event_type VIDEO: post.publish.complete una vez que TikTok ha descargado y verificado el archivo, y después post.publish.publicly_available, con el post_id, cuando la publicación es pública.
¿Cuánto tiempo reintenta TikTok un webhook fallido?
Hasta 72 horas con espera exponencial, tras lo cual el evento se descarta. La entrega es al menos una vez, así que conviene prever duplicados.
¿Puedo registrar mi propio callback en la app de TikTok de easyCoexistence?
No. La configuración de webhooks de la app sigue en manos de easyCoexistence. set_social_webhook_destination envía en su lugar los eventos de comentarios de la cuenta a tu destino.
Sigue leyendo
Conecta tu primer canal en dos minutos.
Sin esperar revisiones de las plataformas. Conecta WhatsApp, Instagram, TikTok u otro canal, pídele a tu IA que publique, responda o te haga un informe, y míralo trabajar.
- 3 días gratis
- Cancela cuando quieras
- Solo APIs oficiales
- Monitorizado 24/7
Verificado el