Mengatur webhook TikTok API for Business
API for Business TikTok mengirim webhook ke satu URL callback per aplikasi developer dan per tipe event, diatur dengan POST /business/webhook/update/ memakai app_id dan secret aplikasi. event_type VIDEO berlangganan ke empat event publikasi postingan, dan COMMENT ke comment.update. Setiap pengiriman adalah POST HTTPS yang ditandatangani di header Tiktok-Signature dengan HMAC-SHA256 yang dikunci dengan secret aplikasi.
easyCoexistence menjaga langganan komentar webhook TikTok tetap aktif untuk aplikasinya, memeriksa tanda tangan TikTok, dan meneruskan setiap event komentar untuk akun Anda ke endpoint HTTPS Anda, ditandatangani dengan secret penandatanganan tersendiri.
Berapa lama TikTok mencoba kembali pengiriman yang tidak dijawab dengan HTTP 200, dengan backoff eksponensial, sebelum membuangnya.
Jumlah ID postingan maksimum yang bisa ditentukan satu item_list untuk membatasi event comment.update ke postingan tertentu.
Nilai terkini dari header webhook-schema-version yang dikirim TikTok bersama setiap pengiriman.
Apa yang tercantum di referensi TikTok untuk endpoint konfigurasi webhook, yang melakukan autentikasi dengan app ID dan secret.
Algoritma di balik Tiktok-Signature: timestamp, titik, dan body, dikunci dengan secret aplikasi lalu dikodekan hex.
Izin aplikasi di bawah TikTok Accounts yang dibutuhkan untuk comment.update; event publikasi membutuhkan Business Content.
Event webhook apa saja yang bisa diterima aplikasi akun TikTok?
Dua kategori, masing-masing berlangganan sebagai event_type sendiri. VIDEO mencakup postingan yang dipublikasikan lewat /business/video/publish/ atau /business/photo/publish/, dan COMMENT mencakup komentar pada postingan foto akun dan postingan video publik, baik yang dipublikasikan lewat API maupun di aplikasi TikTok:
Apa yang dibutuhkan aplikasi sebelum berlangganan?
Akses ke API for Business, aplikasi developer, dan akun TikTok yang telah mengotorisasinya. Panduan berlangganan TikTok menambahkan izin untuk setiap kategori, dan event komentar membutuhkan scope dari setiap pemilik:
- Event publikasi: izin TikTok Accounts, Business Content pada aplikasi.
- Event komentar: izin TikTok Accounts, Business Comment pada aplikasi.
- comment.update: scope comment.list, diberikan oleh pemilik dan tetap berlaku.
- Callback URL di HTTPS yang langsung menjawab HTTP 200.
Bagaimana cara berlangganan?
Dengan POST ke /business/webhook/update/, sekali untuk setiap event_type. Body memuat app_id dan secret, event_type, VIDEO atau COMMENT, dan callback_url; untuk COMMENT juga bisa memuat item_list. Respons mengembalikan app_id, event_type, callback_url dan, jika sudah diatur, item_list. Memanggil ulang untuk event_type yang sama akan mengganti callback URL.
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 mempersempit event komentar?
Ia membatasi comment.update ke postingan yang disebutkan, hingga 100 ID dari /business/video/list/, dan daftar pertama menentukan mode untuk aplikasi sejak saat itu:
- Panggilan COMMENT pertama dengan
item_list: event hanya datang untuk postingan dalam daftar. - Panggilan berikutnya dengan
item_list: postingan baru bergabung dengan yang sudah ada dalam daftar. - Panggilan COMMENT tanpa
item_list, belum ada yang diatur sebelumnya: event datang untuk postingan dari akun yang mengotorisasi aplikasi. - Panggilan COMMENT tanpa
item_list, setelah daftar ada: postingan yang sudah dikonfigurasi tetap seperti semula.
Bagaimana cara memeriksa atau menghapus berlangganan?
GET /business/webhook/list/ dengan app_id, secret dan event_type mengembalikan konfigurasi: callback_url muncul hanya jika ada untuk tipe event itu, dan item_list hanya jika sudah diatur. POST /business/webhook/delete/ dengan app_id, secret dan event_type menghapusnya; untuk COMMENT, item_list dalam panggilan hapus hanya menghapus postingan tersebut, dan tanpa itu event komentar berhenti untuk semua postingan.
Apa yang harus dilakukan callback URL?
Menjawab seketika. TikTok mengirim JSON melalui HTTPS dan menganggap apa pun selain HTTP 200 sebagai pengiriman gagal, lalu mencoba kembali dengan backoff eksponensial hingga 72 jam sebelum membuang event. Pengiriman bersifat setidaknya sekali, jadi event yang sama bisa datang dua kali dan pemrosesannya harus idempoten. Setiap permintaan membawa tiga header yang layak dicatat, tiktok-signature, webhook-schema-version dan x-tt-logid, serta body berisi client_key, event, create_time dalam detik, user_openid, yaitu business_id akun, dan content, sebuah string JSON yang diserialisasi.
Bagaimana cara memverifikasi Tiktok-Signature?
Pisahkan header, t=<unix>,s=<hex>, pada koma lalu pada tanda sama dengan. Bangun pesan yang ditandatangani dari nilai t, titik, dan body permintaan, hitung HMAC-SHA256-nya yang dikunci dengan secret aplikasi, kodekan hasilnya ke hex, lalu bandingkan dengan s. Setelah itu periksa seberapa lama t: TikTok menandatangani waktu pengiriman untuk mencegah serangan replay, dan contohnya menerima penundaan 5 detik. Bekerja dari body mentah seperti yang diterima mencegah serialisasi ulang JSON yang berbeda.
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 cara menerima event TikTok melalui easyCoexistence?
Dengan memberi akun sebuah tujuan. easyCoexistence menjaga aplikasinya sendiri tetap berlangganan ke COMMENT, memeriksa tanda tangan TikTok, menjawab TikTok seketika, dan mengirim setiap comment.update untuk akun yang terhubung ke endpoint HTTPS yang diatur untuknya. Dari Claude atau ChatGPT, set_social_webhook_destination menerima account_id dan url, atau null untuk berhenti, lalu mengembalikan secret penandatanganan yang hanya ditampilkan sekali; memanggilnya lagi menerbitkan yang baru. Event publikasi tidak diteruskan: get_tiktok_publish_status sebagai gantinya mengikuti postingan.
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 cara mengaturnya dengan Partner API?
Dengan PUT /channels/{id}/webhook pada https://easycoexistence.com/api/v1, kunci ec_live_ Anda sebagai bearer token, dan body berisi {"url": "https://..."}. Respons memuat webhook_url, signing_secret dan note, dan {"url": null} menghentikan peneruskan. URL harus memakai HTTPS di host publik; saluran yang tidak dikenal mengembalikan 404 not_found, yang sudah dihapus 409 removed, dan yang ditangguhkan 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 pengiriman itu berbeda?
Forward dari easyCoexistence ditandatangani dan dibentuk berbeda dari pengiriman TikTok sendiri, sehingga penerima yang ditulis untuk salah satunya perlu perubahan untuk yang lain. Payload yang diteruskan mempertahankan field komentar TikTok, dengan content sudah diurai dan ID-nya berupa string; yang berubah adalah cara setiap pengiriman ditandatangani, dibatasi cakupannya, dan dicoba kembali:
| 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 mengonfigurasi
- 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.
Kesalahan umum
- Memproses event sebelum menjawab. TikTok meminta 200 seketika dan mencoba kembali pengiriman yang tidak terkonfirmasi, jadi antrekan pekerjaannya dan balas dulu.
- Mengirim item_list pada langganan COMMENT pertama tanpa sengaja. Sejak itu, TikTok hanya melaporkan event komentar untuk postingan dalam daftar.
- Memverifikasi dengan token akses. TikTok menandatangani webhook dengan secret aplikasi, yaitu secret yang sama dengan yang diterima /business/webhook/update/.
- Mengarahkan dua lingkungan ke satu aplikasi. Setiap tipe event menyimpan satu callback_url per aplikasi, dan panggilan /business/webhook/update/ baru akan menggantikannya.
Atur dengan set_social_webhook_destination dari Claude atau ChatGPT, atau dengan PUT /channels/{id}/webhook. US$ 9 hingga US$ 0.75 per koneksi per bulan, turun seiring Anda menambah koneksi, dengan 3 hari pertama gratis.
Pertanyaan yang sering diajukan
Header apa saja yang dibawa pengiriman webhook TikTok?
tiktok-signature, webhook-schema-version, saat ini v1.0, dan x-tt-logid, ID pengiriman. Body JSON memuat client_key, event, create_time, user_openid dan content.
Apakah TikTok mengirim webhook saat video dipublikasikan?
Ya, dengan event_type VIDEO: post.publish.complete setelah TikTok selesai mengunduh dan memeriksa file, lalu post.publish.publicly_available, dengan post_id, setelah postingan menjadi publik.
Berapa lama TikTok mencoba kembali webhook yang gagal?
Hingga 72 jam dengan backoff eksponensial, setelah itu event dibuang. Pengiriman bersifat setidaknya sekali, jadi siapkan untuk duplikat.
Bisakah saya mendaftarkan callback sendiri di aplikasi TikTok easyCoexistence?
Tidak. Pengaturan webhook aplikasi tetap pada easyCoexistence. set_social_webhook_destination mengirim event komentar akun ke Anda sebagai gantinya.
Lanjut membaca
Hubungkan saluran pertama Anda dalam dua menit.
Tanpa menunggu peninjauan platform. Hubungkan WhatsApp, Instagram, TikTok, atau saluran lainnya, lalu minta AI Anda untuk memposting, membalas, atau membuat laporan, dan lihat hasilnya langsung.
- Gratis 3 hari
- Batalkan kapan saja
- Hanya API resmi
- Dipantau 24/7
Diverifikasi pada