Configurer les webhooks de TikTok API for Business
L'API for Business de TikTok envoie les webhooks vers une seule URL de callback par application développeur et par type d'événement, définie avec POST /business/webhook/update/ à l'aide de l'app_id et du secret de l'application. event_type VIDEO abonne aux quatre événements de publication, et COMMENT à comment.update. Chaque livraison est un POST HTTPS signé dans l'en-tête Tiktok-Signature par un HMAC-SHA256 dont la clé est le secret de l'application.
easyCoexistence garde le webhook de commentaires de TikTok abonné pour son application, vérifie la signature de TikTok et transmet chaque événement de commentaire de votre compte à votre endpoint HTTPS, signé avec un secret propre.
Durée pendant laquelle TikTok réessaie une livraison sans réponse HTTP 200, avec un délai qui augmente de façon exponentielle, avant de l'abandonner.
Nombre maximal d'identifiants de publications qu'un même item_list peut désigner pour restreindre les événements comment.update à certaines publications.
Valeur actuelle de l'en-tête webhook-schema-version que TikTok envoie avec chaque livraison.
Ce que la référence de TikTok énumère pour les endpoints de configuration des webhooks, qui s'authentifient avec l'app ID et le secret.
Algorithme derrière Tiktok-Signature : l'horodatage, un point et le corps, signés avec le secret de l'application puis encodés en hexadécimal.
Permission de l'application sous TikTok Accounts nécessaire pour comment.update ; les événements de publication demandent Business Content.
Quels événements webhook une application de compte TikTok peut-elle recevoir ?
Deux catégories, chacune abonnée comme son propre event_type. VIDEO couvre les publications faites via /business/video/publish/ ou /business/photo/publish/, et COMMENT couvre les commentaires sur les publications photo et vidéo publiques du compte, qu'elles aient été publiées via l'API ou dans l'application TikTok :
De quoi l'application a-t-elle besoin avant de s'abonner ?
Un accès à l'API for Business, une application développeur et des comptes TikTok qui l'ont autorisée. Le guide d'abonnement de TikTok ajoute une permission pour chaque catégorie, et l'événement de commentaire nécessite un scope accordé par chaque propriétaire :
- Événements de publication : la permission TikTok Accounts, Business Content sur l'application.
- Événements de commentaire : la permission TikTok Accounts, Business Comment sur l'application.
- comment.update : le scope comment.list, accordé par le propriétaire et maintenu valide.
- Une URL de callback en HTTPS qui répond HTTP 200 immédiatement.
Comment s'abonner ?
Par un POST vers /business/webhook/update/, une fois par event_type. Le corps prend app_id et secret, l'event_type, VIDEO ou COMMENT, et callback_url ; pour COMMENT, il peut aussi prendre item_list. La réponse renvoie app_id, event_type, callback_url et, si l'un est configuré, item_list. Un nouvel appel pour le même event_type remplace l'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" }
}Comment item_list restreint-il les événements de commentaire ?
Il limite comment.update aux publications qu'il désigne, jusqu'à 100 identifiants issus de /business/video/list/, et le premier appel fixe le mode de l'application à partir de là :
- Premier appel COMMENT avec
item_list: les événements n'arrivent que pour les publications listées. - Appels suivants avec
item_list: les nouvelles publications s'ajoutent à celles déjà listées. - Appel COMMENT sans
item_list, aucune liste définie auparavant : les événements arrivent pour les publications des comptes qui ont autorisé l'application. - Appel COMMENT sans
item_list, une liste existant déjà : les publications configurées restent telles quelles.
Comment vérifier ou supprimer un abonnement ?
GET /business/webhook/list/ avec app_id, secret et event_type renvoie la configuration : callback_url n'apparaît que si une URL existe pour ce type d'événement, et item_list seulement si une liste a été définie. POST /business/webhook/delete/ avec app_id, secret et event_type le supprime ; pour COMMENT, un item_list dans l'appel de suppression ne retire que ces publications, et sans lui les événements de commentaire cessent pour toutes les publications.
Que doit faire l'URL de callback ?
Répondre immédiatement. TikTok envoie du JSON en POST sur HTTPS et considère tout code autre qu'un HTTP 200 comme une livraison échouée, en réessayant avec un délai exponentiel pendant jusqu'à 72 heures avant d'abandonner l'événement. La livraison se fait au moins une fois, donc un même événement peut arriver deux fois et le traitement doit être idempotent. Chaque requête porte trois en-têtes à journaliser : tiktok-signature, webhook-schema-version et x-tt-logid, ainsi qu'un corps composé de client_key, event, create_time en secondes, user_openid, qui correspond au business_id du compte, et content, une chaîne JSON sérialisée.
Comment vérifier Tiktok-Signature ?
Découper l'en-tête, t=<unix>,s=<hex>, sur les virgules, puis sur le signe égal. Construire le message signé à partir de la valeur t, d'un point et du corps de la requête, calculer son HMAC-SHA256 avec le secret de l'application comme clé, l'encoder en hexadécimal et le comparer à s. Vérifier ensuite l'ancienneté de t : TikTok signe l'heure de livraison pour contrer les rejeux, et son exemple accepte un délai de 5 secondes. Travailler sur le corps brut tel que reçu évite de resérialiser le JSON différemment.
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_ageComment recevoir les événements TikTok via easyCoexistence ?
En donnant un destinataire au compte. easyCoexistence garde sa propre application abonnée à COMMENT, vérifie la signature de TikTok, répond immédiatement à TikTok, et transmet chaque comment.update d'un compte connecté à l'endpoint HTTPS défini pour ce compte. Depuis Claude ou ChatGPT, set_social_webhook_destination prend account_id et une url, ou null pour arrêter, et renvoie un secret de signature affiché une seule fois ; un nouvel appel en génère un autre. Les événements de publication ne sont pas transmis : get_tiktok_publish_status suit une publication à la place.
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. ..."
}Comment le configurer avec l'API partenaire ?
Avec PUT /channels/{id}/webhook sur https://easycoexistence.com/api/v1, votre clé ec_live_ comme token bearer, et un corps {"url": "https://..."}. La réponse contient webhook_url, signing_secret et une note, et {"url": null} arrête la transmission. L'URL doit utiliser HTTPS sur un hôte public ; un canal inconnu renvoie 404 not_found, un canal supprimé 409 removed et un canal suspendu 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 quoi les deux livraisons diffèrent-elles ?
Un transfert depuis easyCoexistence est signé et structuré différemment de la livraison native de TikTok, donc un récepteur écrit pour l'une doit être modifié pour l'autre. Le payload transmis conserve les champs de commentaire de TikTok, avec content analysé et ses identifiants sous forme de chaînes ; ce qui change, c'est la signature, la portée et les réessais de chaque livraison :
| 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 |
Comment le configurer
- 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.
Erreurs courantes
- Traiter l'événement avant de répondre. TikTok demande un HTTP 200 immédiat et réessaie les livraisons dont il ne voit pas l'accusé de réception ; mettez donc le travail en file d'attente et répondez d'abord.
- Envoyer item_list dès le premier abonnement COMMENT par erreur. Ensuite, TikTok ne signale les événements de commentaire que pour les publications listées.
- Vérifier avec le token d'accès. TikTok signe les webhooks avec le secret de l'application, le même que celui que prend /business/webhook/update/.
- Faire pointer deux environnements vers une même application. Chaque type d'événement ne garde qu'une callback_url par application, et un nouvel appel à /business/webhook/update/ la remplace.
Configurez-le avec set_social_webhook_destination depuis Claude ou ChatGPT, ou avec PUT /channels/{id}/webhook. De US$ 9 à US$ 0.75 par connexion et par mois, en baisse à mesure que vous ajoutez des connexions, avec un essai gratuit de 3 jours.
Questions fréquemment posées
Quels en-têtes une livraison webhook TikTok contient-elle ?
tiktok-signature, webhook-schema-version, actuellement v1.0, et x-tt-logid, l'identifiant de la livraison. Le corps JSON contient client_key, event, create_time, user_openid et content.
TikTok envoie-t-il un webhook lorsqu'une vidéo est publiée ?
Oui, avec event_type VIDEO : post.publish.complete une fois que TikTok a téléchargé et vérifié le fichier, puis post.publish.publicly_available, avec le post_id, une fois la publication rendue publique.
Combien de temps TikTok réessaie-t-il un webhook en échec ?
Jusqu'à 72 heures avec un délai exponentiel, après quoi l'événement est abandonné. La livraison se fait au moins une fois, donc prévoyez des doublons.
Puis-je enregistrer mon propre callback sur l'application TikTok d'easyCoexistence ?
Non. Les paramètres webhook de l'application restent chez easyCoexistence. set_social_webhook_destination envoie à la place les événements de commentaire du compte vers vous.
Poursuivre la lecture
Connectez votre premier canal en deux minutes.
Aucune validation de plateforme à attendre. Connectez WhatsApp, Instagram, TikTok ou un autre canal, puis demandez à votre IA de publier, de répondre ou de faire un rapport, et regardez-la travailler.
- 3 jours gratuits
- Résiliable à tout moment
- API officielles uniquement
- Supervisé 24/7
Vérifié le