Log masukMulakan percubaan percuma
easyCoexistence API rasmi

Mengesahkan webhook TikTok: header tandatangan dan cara menyemaknya

Setiap penghantaran webhook TikTok API for Business ditandatangani dalam header Tiktok-Signature berbentuk t=<saat unix>,s=<hex>, dengan s ialah HMAC-SHA256 bagi nilai t, titik dan badan permintaan, dikunci dengan rahsia aplikasi pembangun. Untuk mengesahkannya, kira semula HMAC ke atas badan mentah seperti yang diterima, bandingkan dengan s dalam masa malar dan tolak t yang usang.

easyCoexistence menyemak tandatangan TikTok pada setiap peristiwa komen yang diterima aplikasinya, kemudian menghantar ke hadapan peristiwa komen akaun bersambung ke endpoint HTTPS anda, ditandatangani dalam X-EC-Signature dengan rahsia untuk akaun itu sahaja.

t and s

Dua bahagian dalam Tiktok-Signature: cap masa Unix bagi penghantaran itu dalam saat dan tandatangan yang dijana TikTok untuknya.

5 seconds

acceptableDelay dalam contoh Node TikTok, yang menolak penghantaran yang ditandatangani betul tetapi lebih lama daripada tempoh itu.

x-tt-logid

Header yang membawa ID unik setiap penghantaran, yang TikTok minta penerima log untuk penyelesaian masalah.

BRAND_MENTION

Jenis peristiwa bagi webhook sebutan, yang panduan langganannya merujuk kepada pengesahan tandatangan yang sama.

v1

Bahagian tandatangan dalam header X-EC-Signature easyCoexistence, iaitu HMAC-SHA256 bagi t, titik dan badan mentah.

Bagaimana rupa header Tiktok-Signature?

Dua bahagian, dipisahkan dengan koma: t, cap masa Unix dalam saat bagi penghantaran itu, dan s, tandatangan, sepanjang 64 aksara heksadesimal. Halaman TikTok menulis nama ini sebagai TikTok-Signature, Tiktok-Signature dan tiktok-signature; nama header HTTP tidak peka huruf besar kecil, jadi bacalah tanpa mengira huruf, seperti yang sudah dilakukan kebanyakan rangka kerja. Header lain dalam contoh penghantaran TikTok:

Headers from TikTok's sample delivery
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: 202201120803530102451591650189C78

Bait mana yang ditandatangani TikTok?

Nilai t sebagai rentetan, titik, kemudian badan. Panduan TikTok memanggil bahagian akhir itu salinan JSON bersiri bagi badan permintaan, dan contoh Node-nya membina semula salinan itu dengan menjalankan JSON.stringify ke atas objek yang sudah dihurai. Cara itu hanya menghasilkan bait yang sama dengan TikTok selagi kedua-dua serialisasi bersetuju tentang jarak, susunan kunci dan pelarian, jadi cincang badan tepat seperti ketika ia tiba, sebelum sebarang middleware JSON membacanya.

Rahsia mana yang menjadi kunci?

Rahsia aplikasi pembangun, yang terdapat di bawah My Apps, App Detail, Basic Information dalam portal pembangun TikTok. Ia ialah nilai yang sudah dihantar aplikasi sebagai secret ke /business/webhook/update/ dan sebagai client_secret ke endpoint token. Satu rahsia menandatangani penghantaran bagi setiap akaun yang membenarkan aplikasi, jadi penerima tidak perlukan kunci bagi setiap akaun, dan token akses mahupun ID aplikasi tidak terlibat.

Bagaimana anda menyemaknya dalam Node.js?

Dengan node:crypto dan badan mentah. Fungsi di bawah memisahkan header, mengira semula HMAC ke atas t, titik dan bait badan, membandingkan hasilnya dalam masa malar, kemudian menyemak umur t. Ia menerima nama bahagian tandatangan sebagai argumen, jadi kod yang sama turut menyemak penghantaran ke hadapan easyCoexistence, yang bahagian itu dinamakan v1 dan kuncinya ialah rahsia penandatanganan akaun:

Node.js and Express: TikTok's deliveries and easyCoexistence's forwards
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
});

Berapa lamakah penghantaran boleh berumur sebelum anda menolaknya?

TikTok menyerahkan had masa kepada penerima: kira jurang antara jam anda dan t, kata panduannya, dan putuskan sama ada ia boleh diterima. Contoh Node-nya membenarkan 5 saat, cukup ketat sehingga jam pelayan yang tersasar beberapa saat boleh menolak penghantaran yang sah; kod di atas membenarkan 300, tetingkap yang easyCoexistence minta penerima gunakan pada penghantaran ke hadapannya sendiri. Ukur dari t, masa penghantaran yang dilindungi tandatangan, bukan dari create_time dalam badan, yang menandakan bila peristiwa berlaku. Dalam contoh TikTok, t jatuh satu saat selepas create_time.

Apa yang perlu endpoint jawab?

200 sebaik sahaja tandatangan disahkan, dengan kerja dilakukan kemudian, kerana TikTok menganggap sebarang status lain sebagai penghantaran gagal dan menghantarnya semula. Bagi tandatangan yang tidak sepadan, contoh TikTok menjawab dengan status 4xx dan mencatat header x-tt-logid, yang mengenal pasti permintaan itu jika anda melaporkan masalah kepada TikTok. client_key dalam badan menamakan aplikasi pembangun, jadi membandingkannya dengan ID aplikasi anda sendiri ialah semakan kedua yang murah.

Bagaimana URL panggil balik didaftarkan, dan adakah ia disahkan?

Melalui satu panggilan API, dan TikTok tidak mendokumentasikan sebarang permintaan cabaran yang menguji URL dahulu. POST /business/webhook/update/ mengambil app_id, rahsia, event_type dan callback_url HTTPS: VIDEO bagi peristiwa penerbitan, COMMENT bagi comment.update dan, pada Mentions API, BRAND_MENTION bagi brand.mention.event. Ketiga-tiganya tiba ditandatangani dengan cara yang sama, dan GET /business/webhook/list/ menunjukkan URL yang didaftarkan bagi setiap jenis peristiwa. Bukti asal ialah tandatangan pada setiap penghantaran.

Bolehkah anda menyemak Tiktok-Signature pada peristiwa yang easyCoexistence hantar ke hadapan?

Tidak, dan tiada keperluan untuk itu. TikTok menandatangani penghantaran tersebut dengan rahsia aplikasi pembangun easyCoexistence sendiri, yang tiada alat atau API akan berikan. easyCoexistence menyemak tandatangan itu apabila setiap peristiwa tiba, menjawab 401 kepada yang gagal, mengabaikan badan yang client_key-nya menamakan aplikasi lain, dan kemudian menandatangani penghantaran ke hadapannya kepada anda dalam X-EC-Signature dengan rahsia penandatanganan akaun bersambung itu.

Bagaimana easyCoexistence menandatangani apa yang dihantar ke hadapan?

Dalam header X-EC-Signature, t=<unix>,v1=<hex>, dengan t ialah masa penghantaran ke hadapan dan v1 ialah HMAC-SHA256 heksadesimal bagi t, titik dan badan tepat seperti yang dihantar. Kuncinya ialah rahsia penandatanganan akaun, iaitu whsec_ diikuti 32 aksara, digunakan secara penuh termasuk awalan. Antara header sendiri, easyCoexistence hanya menetapkan Content-Type dan header ini, tanpa header peristiwa, jadi baca nama peristiwa daripada entry.event:

A forwarded TikTok comment event, as sent
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 berlaku apabila rahsia penandatanganan diganti?

Rahsia baharu menandatangani bermula dari penghantaran ke hadapan seterusnya. Memanggil set_social_webhook_destination atau PUT /channels/{id}/webhook sekali lagi memulangkan rahsia baharu dan serta-merta membatalkan yang lama, dan setiap penghantaran ke hadapan dihantar sekali sahaja, jadi peristiwa yang pelayan anda tolak semasa peralihan akan hilang. Terima kedua-dua rahsia selama beberapa minit semasa yang baharu dilancarkan. Peristiwa status tentang saluran dan siaran menggunakan rahsia lain, iaitu yang terdapat di Dashboard, Profile, Developers, dan tiba dengan header X-EC-Event dan X-EC-Delivery, dicuba semula selama kira-kira 33 jam.

Kesilapan biasa

  • Mengesahkan badan yang sudah dihurai oleh rangka kerja. Middleware JSON menyerahkan objek, dan membuat siri semula boleh mengubah bait TikTok; baca badan mentah pada laluan webhook.
  • Menjawab 200 kepada penghantaran yang tandatangannya gagal. TikTok berhenti menghantar peristiwa sebaik ia nampak 200, jadi penghantaran sah yang ditolak oleh semakan yang tersalah konfigurasi akan hilang; 4xx membuatkan TikTok mencuba semula sehingga 72 jam.
  • Membandingkan tandatangan dengan ===, seperti contoh TikTok. Perbandingan dalam masa malar seperti timingSafeEqual tidak mendedahkan berapa banyak tandatangan palsu yang sepadan.
  • Menyahkod Base64 rahsia easyCoexistence atau memotong awalan whsec_-nya. Kunci HMAC ialah keseluruhan rentetan, tepat seperti yang dipaparkan sekali sahaja.
Menggunakan EasyCoexistence untuk ini

Tetapkan endpoint dengan set_social_webhook_destination dari Claude atau ChatGPT, atau dengan PUT /channels/{id}/webhook. US$ 9 hingga US$ 0.75 setiap sambungan sebulan, menurun apabila anda menambah sambungan, dengan 3 hari pertama percuma.

Soalan lazim

Apakah x-tt-logid dalam webhook TikTok?

Header yang membawa ID unik setiap penghantaran. TikTok meminta penerima log ID itu kerana ia mengenal pasti permintaan apabila anda melaporkan masalah kepada TikTok.

Adakah TikTok menghantar cabaran untuk mengesahkan URL webhook baharu?

TikTok tidak mendokumentasikan sebarang cabaran bagi API for Business-nya. Panggilan /business/webhook/update/ mendaftarkan URL, dan penghantaran kemudian tiba dengan Tiktok-Signature untuk pelayan anda semak.

Mengapa tandatangan webhook TikTok saya tidak pernah sepadan?

Semak input dan kunci: HMAC mesti meliputi t, titik dan badan mentah seperti yang diterima, menggunakan rahsia aplikasi, dan dibandingkan dengan nilai selepas s= dan bukannya keseluruhan header.

Bagaimana saya mengesahkan peristiwa TikTok yang dihantar ke hadapan oleh easyCoexistence?

Dengan X-EC-Signature dan rahsia penandatanganan yang dipaparkan semasa anda menetapkan destinasi: kira HMAC-SHA256 ke atas t, titik dan badan mentah, bandingkan dengan v1, dan tolak t yang melebihi 5 minit.

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