AccediInizia la prova gratuita
easyCoexistence API ufficiali

Configurare i webhook della TikTok API for Business

L'API for Business di TikTok invia i webhook a un unico URL di callback per app per sviluppatori e per tipo di evento, impostato con POST /business/webhook/update/ usando app_id e secret dell'app. event_type VIDEO iscrive i quattro eventi di pubblicazione dei post, e COMMENT iscrive comment.update. Ogni consegna è una POST HTTPS firmata nell'header Tiktok-Signature con un HMAC-SHA256 calcolato con il secret dell'app.

easyCoexistence mantiene iscritto il webhook di commento di TikTok per la propria app, verifica la firma di TikTok e inoltra ogni evento di commento per il tuo account all'endpoint HTTPS, firmato con un secret proprio.

72 hours

Quanto tempo TikTok riprova una consegna senza risposta HTTP 200, con backoff esponenziale, prima di scartarla.

100

Quanti ID di post al massimo può indicare un item_list per limitare gli eventi comment.update a determinati post.

v1.0

Valore attuale dell'header webhook-schema-version che TikTok invia con ogni consegna.

No permission

Cosa elenca il riferimento di TikTok per gli endpoint di configurazione dei webhook, che si autenticano con app ID e secret.

HMAC-SHA256

Algoritmo alla base di Tiktok-Signature: il timestamp, un punto e il body, con chiave il secret dell'app e codifica esadecimale.

Business Comment

Permesso dell'app in TikTok Accounts necessario per comment.update; gli eventi di pubblicazione richiedono Business Content.

Quali eventi webhook può ricevere un'app per l'account TikTok?

Due categorie, ciascuna iscritta come event_type separato. VIDEO copre i post pubblicati tramite /business/video/publish/ o /business/photo/publish/, e COMMENT copre i commenti sui post foto dell'account e sui video pubblici, che siano stati pubblicati tramite API o nell'app 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

Cosa serve all'app prima di iscriversi?

Accesso all'API for Business, un'app per sviluppatori e gli account TikTok che l'hanno autorizzata. La guida alle iscrizioni di TikTok aggiunge un permesso per ogni categoria, e l'evento di commento richiede uno scope da ciascun proprietario:

  • Eventi di pubblicazione: il permesso TikTok Accounts, Business Content sull'app.
  • Eventi di commento: il permesso TikTok Accounts, Business Comment sull'app.
  • comment.update: lo scope comment.list, concesso dal proprietario e mantenuto valido.
  • Un URL di callback in HTTPS che risponde subito con HTTP 200.

Come ci si iscrive?

Con una POST a /business/webhook/update/, una volta per event_type. Il body accetta app_id e secret, l'event_type, VIDEO o COMMENT, e callback_url; per COMMENT può accettare anche item_list. La risposta ripete app_id, event_type, callback_url e, se ne è configurato uno, item_list. Richiamarlo per lo stesso event_type sostituisce l'URL di 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" }
}

In che modo item_list limita gli eventi di commento?

Limita comment.update ai post che indica, fino a 100 ID da /business/video/list/, e la prima lista stabilisce la modalità per l'app da quel momento in poi:

  • Prima chiamata COMMENT con item_list: gli eventi arrivano solo per i post indicati.
  • Chiamate successive con item_list: i nuovi post si aggiungono a quelli già elencati.
  • Chiamata COMMENT senza item_list, nessuna lista impostata prima: gli eventi arrivano per i post degli account che hanno autorizzato l'app.
  • Chiamata COMMENT senza item_list, con una lista già presente: i post configurati restano come sono.

Come si controlla o si rimuove un'iscrizione?

GET /business/webhook/list/ con app_id, secret e event_type restituisce la configurazione: callback_url compare solo se esiste per quel tipo di evento, e item_list solo se è stato impostato. POST /business/webhook/delete/ con app_id, secret e event_type la rimuove; per COMMENT, un item_list nella chiamata di eliminazione rimuove solo quei post, e senza di esso gli eventi di commento si fermano per tutti i post.

Cosa deve fare l'URL di callback?

Rispondere subito. TikTok invia un JSON in POST via HTTPS e considera fallita ogni consegna diversa da un HTTP 200, riprovando con backoff esponenziale per fino a 72 ore prima di scartare l'evento. La consegna è almeno una volta, quindi lo stesso evento può arrivare due volte e l'elaborazione deve essere idempotente. Ogni richiesta porta tre header utili da registrare: tiktok-signature, webhook-schema-version e x-tt-logid, e un body con client_key, event, create_time in secondi, user_openid, che è il business_id dell'account, e content, una stringa JSON serializzata.

Come si verifica Tiktok-Signature?

Dividere l'header, t=<unix>,s=<hex>, prima sulle virgole e poi sul segno di uguale. Costruire il messaggio firmato con il valore di t, un punto e il body della richiesta, calcolarne un HMAC-SHA256 con chiave il secret dell'app, codificarlo in esadecimale e confrontarlo con s. Poi verificare quanto è vecchio t: TikTok firma l'orario di consegna per impedire gli attacchi di replay, e il suo esempio accetta un ritardo di 5 secondi. Lavorare sul body grezzo così come ricevuto evita di riserializzare il JSON in modo diverso.

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

Come si ricevono gli eventi TikTok tramite easyCoexistence?

Assegnando all'account una destinazione. easyCoexistence mantiene la propria app iscritta a COMMENT, verifica la firma di TikTok, risponde subito a TikTok e inoltra con una POST ogni comment.update per un account collegato all'endpoint HTTPS impostato per quell'account. Da Claude o ChatGPT, set_social_webhook_destination accetta account_id e url, oppure null per fermarsi, e restituisce un secret di firma mostrato una sola volta; richiamarlo genera un nuovo secret. Gli eventi di pubblicazione non vengono inoltrati: get_tiktok_publish_status segue invece un 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. ..."
}

Come si imposta con la Partner API?

Con PUT /channels/{id}/webhook su https://easycoexistence.com/api/v1, la chiave ec_live_ come bearer token e un body {"url": "https://..."}. La risposta contiene webhook_url, signing_secret e una nota, e {"url": null} interrompe l'inoltro. L'URL deve usare HTTPS su un host pubblico; un canale sconosciuto restituisce 404 not_found, uno rimosso 409 removed e uno sospeso 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": "..." }

In cosa differiscono le due consegne?

Un inoltro da easyCoexistence è firmato e strutturato in modo diverso dalla consegna propria di TikTok, quindi un ricevitore scritto per l'una richiede modifiche per l'altra. Il payload inoltrato mantiene i campi di commento di TikTok, con content analizzato e i suoi ID come stringhe; cambia invece come ogni consegna viene firmata, limitata e riprovata:

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

Come configurarlo

  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.

Errori comuni

  • Elaborare l'evento prima di rispondere. TikTok chiede un 200 immediato e riprova le consegne di cui non vede conferma, quindi metti il lavoro in coda e rispondi per prima cosa.
  • Inviare item_list alla prima iscrizione COMMENT per errore. Da quel momento TikTok segnala gli eventi di commento solo per i post elencati.
  • Verificare con il token di accesso. TikTok firma i webhook con il secret dell'app, lo stesso che accetta /business/webhook/update/.
  • Puntare due ambienti alla stessa app. Ogni tipo di evento mantiene un callback_url per app, e una nuova chiamata a /business/webhook/update/ lo sostituisce.
Farlo con EasyCoexistence

Impostalo con set_social_webhook_destination da Claude o ChatGPT, oppure con PUT /channels/{id}/webhook. Da US$ 9 a US$ 0,75 per connessione al mese, con calo man mano che aggiungi connessioni, con i primi 3 giorni di prova gratuita.

Domande frequenti

Quali header porta una consegna di webhook TikTok?

tiktok-signature, webhook-schema-version, attualmente v1.0, e x-tt-logid, l'ID della consegna. Il body JSON contiene client_key, event, create_time, user_openid e content.

TikTok invia un webhook quando un video viene pubblicato?

Sì, con event_type VIDEO: post.publish.complete una volta che TikTok ha scaricato e verificato il file, poi post.publish.publicly_available, con il post_id, quando il post diventa pubblico.

Per quanto tempo TikTok riprova un webhook non riuscito?

Fino a 72 ore con backoff esponenziale, dopodiché l'evento viene scartato. La consegna è almeno una volta, quindi aspettati dei duplicati.

Posso registrare un mio callback sull'app TikTok di easyCoexistence?

No. Le impostazioni webhook dell'app restano di easyCoexistence. set_social_webhook_destination invia invece a te gli eventi di commento dell'account.

Continua a leggere

Collega il tuo primo canale in due minuti.

Nessuna revisione delle piattaforme da aspettare. Collega WhatsApp, Instagram, TikTok o un altro canale, poi chiedi alla tua AI di pubblicare, rispondere o fare un report, e guardala al lavoro.

  • 3 giorni gratis
  • Disdici quando vuoi
  • Solo API ufficiali
  • Monitorato 24/7

Verificato il