Verifikasi webhook TikTok: header tanda tangan dan cara memeriksanya
API Bisnis TikTok menandatangani setiap pengiriman webhook dalam header Tiktok-Signature dengan format t=<unix seconds>,s=<hex>, dengan s adalah HMAC-SHA256 dari nilai t, titik, dan body permintaan, dikunci dengan rahasia aplikasi pengembang. Untuk memverifikasinya, hitung ulang HMAC itu atas body mentah seperti yang diterima, bandingkan dengan s secara waktu konstan, dan tolak t yang sudah kedaluwarsa.
easyCoexistence memeriksa tanda tangan TikTok pada setiap event komentar yang diterima aplikasinya, lalu meneruskan event komentar akun terhubung ke endpoint HTTPS Anda, ditandatangani di X-EC-Signature dengan rahasia khusus akun itu.
Dua bagian dalam Tiktok-Signature: stempel waktu Unix dalam detik untuk pengiriman tersebut dan tanda tangan yang dibuat TikTok untuknya.
acceptableDelay pada contoh Node TikTok, yang menolak pengiriman bertanda tangan benar tetapi lebih lama dari batas itu.
Header yang membawa ID unik setiap pengiriman, yang diminta TikTok agar penerima mencatatnya untuk pemecahan masalah.
Tipe event untuk webhook sebutan, yang panduan langganannya mengarah ke verifikasi tanda tangan yang sama.
Bagian tanda tangan dari header X-EC-Signature easyCoexistence, yaitu HMAC-SHA256 dari t, titik, dan body mentah.
Seperti apa header Tiktok-Signature?
Dua bagian, dipisahkan koma: t, stempel waktu Unix dalam detik untuk pengiriman tersebut, dan s, tanda tangannya, sepanjang 64 karakter heksadesimal. Halaman TikTok menulis nama ini sebagai TikTok-Signature, Tiktok-Signature, dan tiktok-signature; nama header HTTP tidak membedakan huruf besar kecil, jadi bacalah tanpa memperhatikan kapitalisasi, seperti yang sudah dilakukan sebagian besar framework. Header lain pada contoh pengiriman TikTok:
content-type: application/json;charset=UTF-8
user-agent: tiktok-webhook
tiktok-signature: t=1641974633,s=dc023ece112b3a07d809896fd929928a132168d95d2a2e43aab0105fbb291df8
webhook-schema-version: v1.0
x-tt-logid: 202201120803530102451591650189C78Byte mana yang ditandatangani TikTok?
Nilai t sebagai string, titik, lalu body. Panduan TikTok menyebut bagian terakhir itu salinan JSON body permintaan yang di-stringify, dan contoh Node-nya membangun ulang salinan dengan menjalankan JSON.stringify pada objek yang sudah diurai. Cara itu hanya mereproduksi byte TikTok selama kedua serializer sepakat soal spasi, urutan kunci, dan escaping, jadi hashlah body persis seperti yang tiba, sebelum middleware JSON mana pun membacanya.
Rahasia mana yang menjadi kunci?
Rahasia aplikasi pengembang, ditemukan di My Apps, App Detail, Basic Information pada portal pengembang TikTok. Itu nilai yang sudah dikirim aplikasi sebagai secret ke /business/webhook/update/ dan sebagai client_secret ke endpoint token. Satu rahasia menandatangani pengiriman untuk setiap akun yang mengotorisasi aplikasi, sehingga penerima tidak memerlukan kunci per akun, dan baik access token maupun ID aplikasi tidak ikut berperan.
Bagaimana cara memeriksanya di Node.js?
Dengan node:crypto dan body mentah. Fungsi di bawah memecah header, menghitung ulang HMAC atas t, titik, dan byte body, membandingkan hasilnya secara waktu konstan, lalu memeriksa usia t. Fungsi ini menerima nama bagian tanda tangan sebagai argumen, sehingga kode yang sama juga memeriksa penerusan easyCoexistence, yang bagian itu disebut v1 dan kuncinya adalah rahasia penandatanganan akun:
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
// Tiktok-Signature reads t=<unix>,s=<hex>; X-EC-Signature reads t=<unix>,v1=<hex>.
function verifySignature(rawBody, header, secret, name, maxAgeSeconds = 300) {
const parts = {};
for (const item of String(header ?? "").split(",")) {
const i = item.indexOf("=");
if (i > 0) parts[item.slice(0, i).trim()] = item.slice(i + 1).trim();
}
const signature = parts[name];
if (!/^\d+$/.test(parts.t ?? "") || !signature) return false;
const expected = createHmac("sha256", secret)
.update(parts.t + ".")
.update(rawBody) // the bytes exactly as they arrived
.digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(signature);
if (a.length !== b.length || !timingSafeEqual(a, b)) return false;
return Math.abs(Date.now() / 1000 - Number(parts.t)) <= maxAgeSeconds;
}
const app = express();
// TikTok to your own developer app: the app secret, part s
app.post("/webhooks/tiktok", express.raw({ type: "application/json" }), (req, res) => {
if (!verifySignature(req.body, req.get("tiktok-signature"), process.env.TIKTOK_APP_SECRET, "s")) {
console.warn("TikTok signature rejected, x-tt-logid:", req.get("x-tt-logid"));
return res.sendStatus(401);
}
res.sendStatus(200); // acknowledge first: TikTok retries anything but a 200
enqueue(req.body.toString("utf8")); // its content field is itself a JSON string
});
// easyCoexistence to your endpoint: the account's whsec_ secret, part v1
app.post("/webhooks/easycoexistence", express.raw({ type: "application/json" }), (req, res) => {
if (!verifySignature(req.body, req.get("x-ec-signature"), process.env.EC_SIGNING_SECRET, "v1")) {
return res.sendStatus(401);
}
res.sendStatus(200);
enqueue(req.body.toString("utf8")); // platform, account_id, external_id, entry
});Seberapa lama pengiriman boleh dianggap valid sebelum ditolak?
TikTok menyerahkan batas waktu kepada penerima: hitung selisih antara jam Anda dan t, kata panduannya, lalu putuskan apakah selisih itu masih dapat ditoleransi. Contoh Node-nya mengizinkan 5 detik, cukup ketat sehingga server yang jamnya meleset beberapa detik bisa menolak pengiriman asli; kode di atas mengizinkan 300, jendela yang diminta easyCoexistence dari penerima untuk penerusannya sendiri. Ukur dari t, waktu pengiriman yang dicakup tanda tangan, bukan dari create_time di body, yang menandai kapan event terjadi. Dalam contoh TikTok, t jatuh satu detik setelah create_time.
Apa yang harus dijawab endpoint?
200 segera setelah tanda tangan cocok, dengan pekerjaan dilakukan sesudahnya, karena TikTok menganggap status lain sebagai pengiriman gagal dan mengirimnya ulang. Untuk tanda tangan yang tidak cocok, contoh TikTok menjawab dengan status 4xx dan mencatat header x-tt-logid, yang mengidentifikasi permintaan jika Anda melaporkan masalah ke TikTok. client_key di body menyebut aplikasi pengembang, jadi membandingkannya dengan ID aplikasi Anda sendiri adalah pemeriksaan kedua yang murah.
Bagaimana URL callback didaftarkan, dan apakah diverifikasi?
Dengan satu panggilan API, dan TikTok tidak mendokumentasikan permintaan tantangan yang menguji URL lebih dulu. POST /business/webhook/update/ menerima app_id, rahasia, event_type, dan callback_url HTTPS: VIDEO untuk event publikasi, COMMENT untuk comment.update, dan, pada Mentions API, BRAND_MENTION untuk brand.mention.event. Ketiganya tiba dengan tanda tangan yang sama, dan GET /business/webhook/list/ menampilkan URL yang terdaftar untuk tipe event. Bukti asal adalah tanda tangan pada setiap pengiriman.
Bisakah Tiktok-Signature diperiksa pada event yang diteruskan easyCoexistence?
Tidak, dan memang tidak perlu. TikTok menandatangani pengiriman itu dengan rahasia aplikasi pengembang easyCoexistence sendiri, yang tidak diberikan oleh alat atau API mana pun. easyCoexistence memeriksa tanda tangan itu saat setiap event tiba, menjawab 401 untuk yang gagal, mengabaikan body yang client_key-nya menyebut aplikasi lain, lalu menandatangani penerusannya kepada Anda di X-EC-Signature dengan rahasia penandatanganan akun terhubung tersebut.
Bagaimana easyCoexistence menandatangani apa yang diteruskannya?
Di header X-EC-Signature, t=<unix>,v1=<hex>, dengan t adalah waktu penerusan dan v1 adalah HMAC-SHA256 heksadesimal dari t, titik, dan body persis seperti yang dikirim. Kuncinya adalah rahasia penandatanganan akun, yaitu whsec_ diikuti 32 karakter, dipakai utuh termasuk prefiksnya. Dari header miliknya, easyCoexistence hanya menyetel Content-Type dan header ini, tanpa header event, jadi bacalah nama event dari entry.event:
POST https://hooks.example.com/tiktok/
Content-Type: application/json
X-EC-Signature: t=1793318405,v1=<HMAC_SHA256_HEX>
{"platform":"tiktok","account_id":"<ACCOUNT_ID>","external_id":"<TIKTOK_OPEN_ID>","entry":{"event":"comment.update","create_time":1793318400,"content":{...}}}
v1 = hex(HMAC-SHA256(key = "whsec_<SECRET>", message = "1793318405." + raw body))Apa yang terjadi saat rahasia penandatanganan diganti?
Rahasia baru menandatangani mulai dari penerusan berikutnya. Memanggil set_social_webhook_destination atau PUT /channels/{id}/webhook lagi mengembalikan rahasia baru dan langsung mencabut yang lama, dan setiap penerusan dikirim hanya sekali, sehingga event yang ditolak server Anda selama peralihan akan hilang. Terimalah kedua rahasia selama beberapa menit sementara yang baru di-deploy. Event status tentang saluran dan postingan memakai rahasia lain, yaitu yang dari Dashboard, Profile, Developers, dan tiba dengan header X-EC-Event dan X-EC-Delivery, dicoba kembali selama sekitar 33 jam.
Kesalahan umum
- Memverifikasi body yang sudah diurai framework. Middleware JSON menyerahkan objek, dan membuat ulangnya dapat mengubah byte TikTok; baca body mentah pada rute webhook.
- Menjawab 200 untuk pengiriman yang tanda tangannya gagal. TikTok berhenti mengirim event setelah melihat 200, sehingga event asli yang ditolak pemeriksaan keliru akan hilang; 4xx membuat TikTok mencoba kembali hingga 72 jam.
- Membandingkan tanda tangan dengan ===, seperti contoh TikTok. Perbandingan waktu konstan seperti timingSafeEqual tidak memperlihatkan seberapa banyak tanda tangan palsu yang cocok.
- Men-decode base64 rahasia easyCoexistence atau memotong prefiks whsec_-nya. Kunci HMAC adalah string utuh, persis seperti yang ditampilkan sekali.
Atur endpoint 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
Apa itu x-tt-logid pada webhook TikTok?
Header yang membawa ID unik setiap pengiriman. TikTok meminta penerima mencatatnya, karena ID itu mengidentifikasi permintaan saat Anda melaporkan masalah ke TikTok.
Apakah TikTok mengirim tantangan untuk memverifikasi URL webhook baru?
TikTok tidak mendokumentasikannya untuk API Bisnis-nya. Panggilan /business/webhook/update/ mendaftarkan URL, lalu pengiriman tiba dengan Tiktok-Signature untuk diperiksa server Anda.
Mengapa tanda tangan webhook TikTok saya tidak pernah cocok?
Periksa input dan kuncinya: HMAC harus mencakup t, titik, dan body mentah seperti yang diterima, memakai rahasia aplikasi, dan dibandingkan dengan nilai setelah s=, bukan seluruh header.
Bagaimana saya memverifikasi event TikTok yang diteruskan easyCoexistence?
Dengan X-EC-Signature dan rahasia penandatanganan yang ditampilkan saat Anda mengatur tujuan: hitung ulang HMAC-SHA256 atas t, titik, dan body mentah, bandingkan dengan v1, dan tolak t yang lebih dari 5 menit.
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