Menyediakan webhook TikTok API for Business
TikTok API for Business menghantar webhook ke satu URL callback bagi setiap aplikasi pembangun dan jenis peristiwa, ditetapkan dengan POST /business/webhook/update/ menggunakan app_id dan app secret. event_type VIDEO melanggan empat peristiwa penerbitan siaran, dan COMMENT melanggan comment.update. Setiap penghantaran ialah POST HTTPS yang ditandatangani dalam header Tiktok-Signature dengan HMAC-SHA256 yang dikunci dengan app secret.
easyCoexistence mengekalkan langganan webhook komen TikTok bagi aplikasinya, menyemak tandatangan TikTok dan menghantar setiap peristiwa komen bagi akaun anda ke endpoint HTTPS anda, ditandatangani dengan secret tersendiri.
Berapa lama TikTok mencuba semula penghantaran yang tidak dijawab dengan HTTP 200, dengan undur secara eksponen, sebelum membuangnya.
Bilangan ID siaran paling banyak yang boleh dinyatakan dalam satu item_list untuk mengehadkan peristiwa comment.update kepada siaran tertentu.
Nilai semasa header webhook-schema-version yang TikTok hantar bersama setiap penghantaran.
Apa yang disenaraikan oleh rujukan TikTok untuk endpoint konfigurasi webhook, yang disahkan menggunakan app ID dan app secret.
Algoritma di sebalik Tiktok-Signature: cap masa, titik dan badan permintaan, dikunci dengan app secret dan dikodkan secara heksadesimal.
Kebenaran aplikasi di bawah TikTok Accounts yang diperlukan untuk comment.update; peristiwa penerbitan memerlukan Business Content.
Peristiwa webhook apakah yang boleh diterima oleh aplikasi akaun TikTok?
Dua kategori, setiap satu dilanggan sebagai event_type tersendiri. VIDEO meliputi siaran yang diterbitkan melalui /business/video/publish/ atau /business/photo/publish/, dan COMMENT meliputi komen pada siaran foto akaun dan siaran video awam, sama ada diterbitkan melalui API atau dalam aplikasi TikTok:
Apakah yang diperlukan oleh aplikasi sebelum melanggan?
Akses kepada API for Business, aplikasi pembangun, dan akaun TikTok yang telah memberi kebenaran kepadanya. Panduan langganan TikTok menambah satu kebenaran bagi setiap kategori, dan peristiwa komen memerlukan skop daripada setiap pemilik:
- Peristiwa penerbitan: kebenaran TikTok Accounts, Business Content pada aplikasi.
- Peristiwa komen: kebenaran TikTok Accounts, Business Comment pada aplikasi.
- comment.update: skop comment.list, diberikan oleh pemilik dan kekal sah.
- URL callback pada HTTPS yang menjawab HTTP 200 dengan segera.
Bagaimana anda melanggan?
Dengan POST ke /business/webhook/update/, sekali bagi setiap event_type. Badan permintaan mengambil app_id dan app secret, event_type, VIDEO atau COMMENT, dan callback_url; bagi COMMENT ia juga boleh mengambil item_list. Respons memulangkan semula app_id, event_type, callback_url dan, apabila ia telah dikonfigurasi, item_list. Memanggilnya semula untuk event_type yang sama akan menggantikan URL 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" }
}Bagaimana item_list mengehadkan peristiwa komen?
Ia mengehadkan comment.update kepada siaran yang dinyatakannya, sehingga 100 ID daripada /business/video/list/, dan senarai pertama menentukan mod bagi aplikasi sejak itu:
- Panggilan COMMENT pertama dengan
item_list: peristiwa tiba untuk siaran yang disenaraikan sahaja. - Panggilan seterusnya dengan
item_list: siaran baharu menyertai siaran yang sudah disenaraikan. - Panggilan COMMENT tanpa
item_list, tiada senarai ditetapkan sebelum ini: peristiwa tiba untuk siaran akaun yang memberi kebenaran kepada aplikasi. - Panggilan COMMENT tanpa
item_list, apabila senarai sudah wujud: siaran yang dikonfigurasi kekal seperti sedia ada.
Bagaimana anda menyemak atau membuang langganan?
GET /business/webhook/list/ dengan app_id, app secret dan event_type memulangkan konfigurasi: callback_url hanya muncul apabila ia wujud bagi jenis peristiwa itu, dan item_list hanya apabila ia telah ditetapkan. POST /business/webhook/delete/ dengan app_id, app secret dan event_type membuangnya; bagi COMMENT, item_list dalam panggilan padam hanya membuang siaran tersebut, dan tanpa item_list peristiwa komen berhenti untuk semua siaran.
Apakah yang mesti dilakukan oleh URL callback?
Menjawab serta-merta. TikTok menghantar JSON melalui HTTPS dan menganggap apa-apa selain HTTP 200 sebagai penghantaran gagal, mencuba semula dengan undur eksponen sehingga 72 jam sebelum membuang peristiwa itu. Penghantaran adalah sekurang-kurangnya sekali, jadi peristiwa yang sama boleh tiba dua kali dan pemprosesan mesti idempoten. Setiap permintaan membawa tiga header yang berbaloi dilog, iaitu tiktok-signature, webhook-schema-version dan x-tt-logid, serta badan yang mengandungi client_key, event, create_time dalam saat, user_openid (business_id akaun), dan content, iaitu rentetan JSON yang telah diserialkan.
Bagaimana anda mengesahkan Tiktok-Signature?
Pisahkan header, t=<unix>,s=<hex>, pada koma dan kemudian pada tanda sama. Bina mesej bertandatangan daripada nilai t, titik dan badan permintaan, kira HMAC-SHA256 untuknya dikunci dengan app secret, kodkan dalam heks dan bandingkan dengan s. Kemudian semak betapa lama t: TikTok menandatangani masa penghantaran untuk menghalang serangan main semula, dan contohnya menerima kelewatan 5 saat. Bekerja daripada badan mentah seperti yang diterima mengelakkan penyerialan semula JSON secara berbeza.
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_ageBagaimana anda menerima peristiwa TikTok melalui easyCoexistence?
Dengan memberikan akaun satu destinasi. easyCoexistence mengekalkan aplikasinya sendiri yang melanggan COMMENT, menyemak tandatangan TikTok, menjawab TikTok serta-merta, dan menghantar setiap comment.update bagi akaun yang disambungkan ke endpoint HTTPS yang ditetapkan untuknya. Daripada Claude atau ChatGPT, set_social_webhook_destination mengambil account_id dan url, atau null untuk berhenti, dan memulangkan secret penandatanganan yang hanya dipaparkan sekali; memanggilnya semula mengeluarkan yang baharu. Peristiwa penerbitan tidak diteruskan: get_tiktok_publish_status sebaliknya menjejak siaran.
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. ..."
}Bagaimana anda menetapkannya dengan Partner API?
Dengan PUT /channels/{id}/webhook pada https://easycoexistence.com/api/v1, kunci ec_live_ anda sebagai bearer token, dan badan {"url": "https://..."}. Respons memuatkan webhook_url, signing_secret dan nota, dan {"url": null} berhenti meneruskan. URL mesti menggunakan HTTPS pada hos awam; saluran yang tidak dikenali memulangkan 404 not_found, yang telah dibuang 409 removed dan yang digantung 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": "..." }Bagaimana kedua-dua penghantaran berbeza?
Penerusan daripada easyCoexistence ditandatangani dan dibentuk secara berbeza daripada penghantaran TikTok sendiri, jadi penerima yang ditulis untuk satu memerlukan perubahan untuk yang lain. Payload yang diteruskan mengekalkan medan komen TikTok, dengan content dihuraikan dan ID-nya sebagai rentetan; yang berubah ialah cara setiap penghantaran ditandatangani, dihadkan skopnya dan dicuba semula:
| 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 |
Cara menetapkannya
- 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.
Kesilapan biasa
- Memproses peristiwa sebelum menjawab. TikTok meminta HTTP 200 dengan segera dan mencuba semula penghantaran yang tidak diakui, jadi letakkan kerja dalam baris gilir dan jawab dahulu.
- Menghantar item_list pada langganan COMMENT pertama secara tidak sengaja. Selepas itu, TikTok melaporkan peristiwa komen untuk siaran yang disenaraikan sahaja.
- Mengesahkan dengan access token. TikTok menandatangani webhook dengan app secret, iaitu yang sama diambil oleh /business/webhook/update/.
- Menunjuk dua persekitaran ke satu aplikasi. Setiap jenis peristiwa mengekalkan satu callback_url bagi setiap aplikasi, dan panggilan /business/webhook/update/ baharu menggantikannya.
Tetapkan dengan set_social_webhook_destination daripada Claude atau ChatGPT, atau dengan PUT /channels/{id}/webhook. Daripada US$ 9 hingga US$ 0.75 setiap sambungan sebulan, menurun apabila anda menambah sambungan, dengan percubaan percuma 3 hari pertama.
Soalan lazim
Apakah header yang dibawa oleh penghantaran webhook TikTok?
tiktok-signature, webhook-schema-version, pada masa ini v1.0, dan x-tt-logid, iaitu ID penghantaran. Badan JSON mengandungi client_key, event, create_time, user_openid dan content.
Adakah TikTok menghantar webhook apabila video diterbitkan?
Ya, dengan event_type VIDEO: post.publish.complete selepas TikTok selesai memuat turun dan menyemak fail, kemudian post.publish.publicly_available, dengan post_id, apabila siaran menjadi awam.
Berapa lama TikTok mencuba semula webhook yang gagal?
Sehingga 72 jam dengan undur eksponen, selepas itu peristiwa dibuang. Penghantaran adalah sekurang-kurangnya sekali, jadi jangkakan pendua.
Bolehkah saya mendaftar callback sendiri pada aplikasi TikTok easyCoexistence?
Tidak. Tetapan webhook aplikasi kekal pada easyCoexistence. set_social_webhook_destination menghantar peristiwa komen akaun kepada anda sebagai ganti.
Teruskan membaca
Sambungkan saluran pertama anda dalam masa dua minit.
Tidak perlu menunggu semakan platform. Sambungkan WhatsApp, Instagram, TikTok atau saluran lain, kemudian minta AI anda menyiarkan, membalas atau melaporkan, dan lihat ia bekerja.
- 3 hari percuma
- Batal bila-bila masa
- API rasmi sahaja
- Dipantau 24/7
Disahkan pada