Kirjaudu sisäänAloita ilmainen kokeilu
easyCoexistence Viralliset API:t

TikTok API for Business -webhookien asetus

TikTokin API for Business lähettää webhookit yhteen callback-URL:iin per kehittäjäsovellus ja tapahtumatyyppi. Osoite asetetaan kutsulla POST /business/webhook/update/ käyttäen sovelluksen app_id:tä ja secretiä. event_type VIDEO tilaa neljä julkaisutapahtumaa, COMMENT tilaa comment.update-tapahtuman. Jokainen toimitus on HTTPS-POST, joka on allekirjoitettu Tiktok-Signature-otsakkeessa HMAC-SHA256-algoritmilla, avaimena sovelluksen secret.

easyCoexistence pitää TikTokin kommenttiwebhookin tilattuna omalle sovellukselleen, tarkistaa TikTokin allekirjoituksen ja välittää jokaisen kommenttitapahtuman tilillesi omaan HTTPS-päätepisteeseesi, allekirjoitettuna omalla salaisuudellaan.

72 hours

Kuinka kauan TikTok yrittää uudelleen toimitusta, johon ei ole vastattu HTTP 200 -koodilla, viiveen kasvaessa eksponentiaalisesti, ennen kuin se hylätään.

100

Kuinka monta julkaisun tunnusta yksi item_list voi nimetä, jotta comment.update-tapahtumat rajataan tiettyihin julkaisuihin.

v1.0

Webhook-schema-version-otsakkeen nykyinen arvo, jonka TikTok lähettää jokaisen toimituksen mukana.

No permission

Mitä TikTokin viite listaa webhook-asetusten päätepisteistä, jotka tunnistautuvat app ID:llä ja secretillä.

HMAC-SHA256

Tiktok-Signature-allekirjoituksen algoritmi: aikaleima, piste ja runko, avaimena sovelluksen secret ja heksaluvuksi koodattuna.

Business Comment

TikTok Accounts -oikeus sovelluksella, jota comment.update tarvitsee; julkaisutapahtumat tarvitsevat Business Content -oikeuden.

Mitä webhook-tapahtumia TikTok-tilin sovellus voi vastaanottaa?

Kaksi luokkaa, kumpikin tilataan omalla event_type-arvollaan. VIDEO kattaa julkaisut, jotka on tehty kutsuilla /business/video/publish/ tai /business/photo/publish/, ja COMMENT kattaa kommentit tilin valokuvajulkaisuihin ja julkisiin videoihin riippumatta siitä, julkaistiinko ne API:n kautta vai TikTok-sovelluksessa:

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

Mitä sovellus tarvitsee ennen tilausta?

Pääsyn API for Businessiin, kehittäjäsovelluksen ja TikTok-tilit, jotka ovat valtuuttaneet sen. TikTokin tilausopas lisää oikeuden kumpaankin luokkaan, ja kommenttitapahtuma vaatii jokaiselta omistajalta yhden laajuuden:

  • Julkaisutapahtumat: sovelluksella TikTok Accounts -oikeus ja Business Content -lupa.
  • Kommenttitapahtumat: sovelluksella TikTok Accounts -oikeus ja Business Comment -lupa.
  • comment.update: omistajan myöntämä ja voimassa pidetty comment.list-laajuus.
  • HTTPS-callback-URL, joka vastaa HTTP 200 heti.

Miten tilaus tehdään?

POST-kutsulla osoitteeseen /business/webhook/update/, kerran jokaista event_type-arvoa kohti. Runko ottaa app_id:n ja secretin, event_type-arvon VIDEO tai COMMENT sekä callback_url:n; COMMENT voi ottaa myös item_list:n. Vastaus toistaa app_id:n, event_type:n, callback_url:n ja, jos sellainen on asetettu, item_list:n. Uusi kutsu samalle event_type:lle korvaa callback-URL:in.

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" }
}

Miten item_list rajaa kommenttitapahtumia?

Se rajaa comment.update-tapahtumat nimettyihin julkaisuihin, enintään 100 tunnukseen /business/video/list/-päätepisteestä, ja ensimmäinen lista määrää sovelluksen tilan siitä eteenpäin:

  • Ensimmäinen COMMENT-kutsu item_list:n kanssa: tapahtumat tulevat vain listatuille julkaisuille.
  • Myöhemmät kutsut item_list:n kanssa: uudet julkaisut liittyvät jo listattujen joukkoon.
  • COMMENT-kutsu ilman item_list:ä, kun mitään ei ole aiemmin asetettu: tapahtumat tulevat niiden tilien julkaisuista, jotka ovat valtuuttaneet sovelluksen.
  • COMMENT-kutsu ilman item_list:ä, kun lista on jo olemassa: määritellyt julkaisut pysyvät ennallaan.

Miten tilauksen voi tarkistaa tai poistaa?

GET /business/webhook/list/ parametreilla app_id, secret ja event_type palauttaa asetukset: callback_url näkyy vain, jos sellainen on kyseiselle tapahtumatyypille, ja item_list vain, jos se on asetettu. POST /business/webhook/delete/ parametreilla app_id, secret ja event_type poistaa tilauksen. COMMENT-tapauksessa delete-kutsun item_list poistaa vain nuo julkaisut, ja ilman sitä kommenttitapahtumat loppuvat kaikilta julkaisuilta.

Mitä callback-URL:n pitää tehdä?

Vastata heti. TikTok lähettää JSON-dataa HTTPS:n yli ja pitää mitä tahansa muuta kuin HTTP 200 -vastausta epäonnistuneena toimituksena. Se yrittää uudelleen eksponentiaalisella viiveellä jopa 72 tuntia ennen tapahtuman hylkäämistä. Toimitus on vähintään kerran, joten sama tapahtuma voi tulla kahdesti, ja käsittelyn täytyy olla idempotentti. Jokaisessa pyynnössä on kolme otsaketta, jotka kannattaa kirjata lokiin: tiktok-signature, webhook-schema-version ja x-tt-logid. Runko sisältää client_key:n, event-kentän, create_time-kentän sekunteina, user_openid-kentän, joka on tilin business_id, ja content-kentän, sarjallistetun JSON-merkkijonon.

Miten Tiktok-Signature tarkistetaan?

Jaa otsake, t=<unix>,s=<hex>, pilkuilla ja sitten yhtäsuuruusmerkillä. Muodosta allekirjoitettu viesti t-arvosta, pisteestä ja pyynnön rungosta, laske siitä HMAC-SHA256 sovelluksen secretillä avainnettuna, koodaa tulos heksaluvuksi ja vertaa sitä s-arvoon. Tarkista lopuksi t:n ikä: TikTok allekirjoittaa toimitusajan replay-hyökkäysten estämiseksi, ja sen esimerkki hyväksyy 5 sekunnin viiveen. Kun käsittelet raakaa runkoa sellaisena kuin se saapui, vältät JSON:n sarjallistamisen uudelleen eri tavalla.

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

Miten vastaanotat TikTok-tapahtumat easyCoexistencen kautta?

Antamalla tilille kohteen. easyCoexistence pitää omaa sovellustaan tilattuna COMMENT-tapahtumille, tarkistaa TikTokin allekirjoituksen, vastaa TikTokille heti ja lähettää jokaisen yhdistetyn tilin comment.update-tapahtuman sille asetettuun HTTPS-päätepisteeseen. Claudesta tai ChatGPT:stä set_social_webhook_destination ottaa account_id:n ja url-kentän, tai null lopettaa lähetykset, ja palauttaa allekirjoitussalaisuuden, joka näytetään vain kerran; uusi kutsu antaa uuden. Julkaisutapahtumia ei välitetä: get_tiktok_publish_status seuraa sen sijaan julkaisua.

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

Miten asetat sen Partner API:n kautta?

PUT-kutsulla polkuun /channels/{id}/webhook osoitteessa https://easycoexistence.com/api/v1, käyttäen ec_live_-avaimesi bearer-tokenina ja runkoa {"url": "https://..."}. Vastaus sisältää webhook_url:n, signing_secret:n ja note-kentän, ja {"url": null} lopettaa välityksen. URL:n on oltava HTTPS julkisella isännällä; tuntematon kanava palauttaa 404 not_found, poistettu 409 removed ja keskeytetty 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": "..." }

Miten kaksi toimitusta eroavat?

easyCoexistencen välittämä toimitus on allekirjoitettu ja muotoiltu eri tavalla kuin TikTokin oma toimitus, joten sitä vastaanottavan palvelun täytyy muuttua, jos se vastaanottaa molemmat. Välitetyn payloadin TikTokin kommenttikentät säilyvät, content on jäsennetty ja tunnukset ovat merkkijonoja. Erot ovat allekirjoituksessa, rajauksessa ja uudelleenyrityksissä:

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

Näin otat sen käyttöön

  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.

Yleiset virheet

  • Tapahtuman käsittely ennen vastaamista. TikTok odottaa välitöntä 200-vastausta ja yrittää uudelleen toimituksia, joita se ei näe kuitatun, joten jonota työ ja vastaa ensin.
  • item_list:n lähettäminen vahingossa ensimmäisessä COMMENT-tilauksessa. Sen jälkeen TikTok raportoi kommenttitapahtumat vain listatuille julkaisuille.
  • Allekirjoituksen tarkistaminen access tokenilla. TikTok allekirjoittaa webhookit sovelluksen secretillä, saman jonka /business/webhook/update/ myös vaatii.
  • Kaksi ympäristöä osoitettu samaan sovellukseen. Jokaisella tapahtumatyypillä on yksi callback_url per sovellus, ja uusi /business/webhook/update/-kutsu korvaa sen.
Näin teet tämän EasyCoexistencen avulla

Aseta se Claudesta tai ChatGPT:stä set_social_webhook_destination-funktiolla tai PUT /channels/{id}/webhook -kutsulla. US$ 9:stä US$ 0,75:een per yhteys kuukaudessa, hinta laskee lisäyhteyksien myötä, ja ensimmäiset 3 päivää ovat ilmaisia.

Usein kysytyt kysymykset

Mitkä otsakkeet TikTok-webhook-toimitus sisältää?

tiktok-signature, webhook-schema-version, tällä hetkellä v1.0, ja x-tt-logid, toimituksen tunniste. JSON-runko sisältää client_key, event, create_time, user_openid ja content.

Lähettääkö TikTok webhookin, kun video julkaistaan?

Kyllä, event_type VIDEO:lla: ensin post.publish.complete, kun TikTok on ladannut ja tarkistanut tiedoston, ja sitten post.publish.publicly_available post_id:n kanssa, kun julkaisu on julkinen.

Kuinka kauan TikTok yrittää uudelleen epäonnistunutta webhookia?

Jopa 72 tuntia eksponentiaalisella viiveellä, jonka jälkeen tapahtuma hylätään. Toimitus on vähintään kerran, joten odota kaksoiskappaleita.

Voinko rekisteröidä oman callbackini easyCoexistencen TikTok-sovellukseen?

Et. Sovelluksen webhook-asetukset pysyvät easyCoexistencella. set_social_webhook_destination lähettää tilin kommenttitapahtumat sen sijaan sinulle.

Lue lisää

Yhdistä ensimmäinen kanavasi kahdessa minuutissa.

Ei alustojen tarkastuksia odotettavana. Yhdistä WhatsApp, Instagram, TikTok tai jokin muu kanava, pyydä sitten tekoälyäsi julkaisemaan, vastaamaan tai raportoimaan ja seuraa, kun se hoitaa homman.

  • 3 päivää ilmaiseksi
  • Peruuta milloin tahansa
  • Vain viralliset API:t
  • Valvottu 24/7

Vahvistettu