Weryfikacja webhooków TikTok: nagłówek podpisu i sposób jego sprawdzania
TikTok API for Business podpisuje każde dostarczenie webhooka w nagłówku Tiktok-Signature o postaci t=<unix seconds>,s=<hex>, gdzie s to HMAC-SHA256 wartości t, kropki i treści żądania, kluczowany sekretem aplikacji developerskiej. Aby go zweryfikować, przelicz HMAC na surowej treści w postaci, w jakiej przyszła, porównaj z s w stałym czasie i odrzuć nieaktualne t.
easyCoexistence sprawdza podpis TikTok przy każdym zdarzeniu komentarza, które otrzymuje jego aplikacja, a następnie przekazuje zdarzenia komentarzy połączonego konta na Twój endpoint HTTPS, podpisane w nagłówku X-EC-Signature sekretem tylko dla tego konta.
Dwie części nagłówka Tiktok-Signature: znacznik czasu Unix dostarczenia w sekundach oraz podpis wygenerowany przez TikTok.
acceptableDelay w przykładzie Node.js TikTok, który odrzuca poprawnie podpisane dostarczenie starsze niż ta wartość.
Nagłówek z unikalnym ID każdego dostarczenia, który TikTok prosi odbiorców zapisywać w logach przy rozwiązywaniu problemów.
Typ zdarzenia dla webhooków wzmianek, którego przewodnik subskrypcji wskazuje tę samą weryfikację podpisu.
Część podpisu nagłówka X-EC-Signature easyCoexistence, czyli HMAC-SHA256 obliczony dla t, kropki i surowej treści.
Jak wygląda nagłówek Tiktok-Signature?
Dwie części, oddzielone przecinkiem: t, czyli znacznik czasu Unix w sekundach tego dostarczenia, oraz s, czyli podpis, długi na 64 znaki szesnastkowe. Strony TikTok zapisują nazwę jako TikTok-Signature, Tiktok-Signature i tiktok-signature; nazwy nagłówków HTTP nie rozróżniają wielkości liter, więc czytaj je bez względu na wielkość, jak robi to już większość frameworków. Pozostałe nagłówki w przykładowym dostarczeniu 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: 202201120803530102451591650189C78Które bajty podpisuje TikTok?
Wartość t jako ciąg znaków, kropkę, a potem treść. Przewodnik TikTok nazywa tę ostatnią część zserializowaną kopią treści żądania, a jego przykład w Node.js odtwarza tę kopię, wywołując JSON.stringify na już sparsowanym obiekcie. Odtwarza to bajty TikTok tylko wtedy, gdy oba serializatory zgadzają się co do odstępów, kolejności kluczy i znaków ucieczki, dlatego haszuj treść dokładnie w postaci, w jakiej przyszła, zanim cokolwiek z middleware JSON ją odczyta.
Który sekret jest kluczem?
Sekret aplikacji developerskiej, znaleziony w My Apps, App Detail, Basic Information w portalu deweloperskim TikTok. To wartość, którą aplikacja już wysyła jako secret do /business/webhook/update/ i jako client_secret do endpointów tokenów. Jeden sekret podpisuje dostarczenia dla każdego konta, które autoryzowało aplikację, więc odbiorca nie potrzebuje klucza dla każdego konta, a w podpisie nie bierze udziału ani access token, ani ID aplikacji.
Jak to sprawdzić w Node.js?
Za pomocą node:crypto i surowej treści. Poniższa funkcja dzieli nagłówek, przelicza HMAC po t, kropce i bajtach treści, porównuje wynik w stałym czasie, a następnie sprawdza wiek t. Jako argument przyjmuje nazwę części podpisu, więc ten sam kod sprawdza też przekazania easyCoexistence, gdzie ta część nazywa się v1, a kluczem jest sekret podpisu konta:
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
});Jak stara może być dostawa, zanim ją odrzucisz?
TikTok zostawia granicę odbiorcy: oblicz różnicę między swoim zegarem a t, pisze jego przewodnik, i zdecyduj, czy jest do przyjęcia. Jego przykład w Node.js dopuszcza 5 sekund, na tyle mało, że serwer z zegarem odchylonym o kilka sekund mógłby odrzucić prawdziwe dostarczenia; kod powyżej dopuszcza 300, czyli okno, którego easyCoexistence wymaga od odbiorców w swoich przekazaniach. Mierz od t, czyli czasu dostarczenia objętego podpisem, a nie od create_time w treści, który oznacza moment wystąpienia zdarzenia. W przykładzie TikTok t przypada sekundę po create_time.
Co powinien zwracać endpoint?
Odpowiedz kodem 200, gdy tylko podpis się zgadza, a pracę wykonaj potem, ponieważ TikTok traktuje każdy inny status jako nieudane dostarczenie i wysyła je ponownie. Przy niezgodnym podpisie przykład TikTok odpowiada statusem 4xx i zapisuje nagłówek x-tt-logid, który identyfikuje żądanie, gdy zgłaszasz problem TikTok. client_key w treści wskazuje aplikację developerską, więc porównanie go z własnym ID aplikacji to tani drugi test.
Jak rejestruje się URL callbacku i czy jest weryfikowany?
Jednym wywołaniem API, a TikTok nie dokumentuje żadnego żądania wyzwania, które najpierw testuje URL. POST /business/webhook/update/ przyjmuje app_id, sekret, event_type i callback_url w formacie HTTPS: VIDEO dla zdarzeń publikacji, COMMENT dla comment.update oraz, w Mentions API, BRAND_MENTION dla brand.mention.event. Wszystkie trzy przychodzą podpisane tak samo, a GET /business/webhook/list/ pokazuje URL zarejestrowany dla typu zdarzenia. Dowodem pochodzenia jest podpis każdego dostarczenia.
Czy można sprawdzić Tiktok-Signature w zdarzeniach, które przekazuje easyCoexistence?
Nie i nic tego nie wymaga. TikTok podpisuje te dostarczenia sekretem własnej aplikacji developerskiej easyCoexistence, którego nie wydaje żadne narzędzie ani API. easyCoexistence sprawdza ten podpis przy każdym zdarzeniu, odpowiada 401 na nieprawidłowy, ignoruje treść, w której client_key wskazuje inną aplikację, a następnie podpisuje przekazanie do Ciebie w nagłówku X-EC-Signature sekretem podpisu tego połączonego konta.
Jak easyCoexistence podpisuje przekazywane dane?
W nagłówku X-EC-Signature o postaci t=<unix>,v1=<hex>, gdzie t to czas przekazania, a v1 to szesnastkowy HMAC-SHA256 obliczony dla t, kropki i treści dokładnie tak, jak została wysłana. Kluczem jest sekret podpisu konta, czyli whsec_ oraz 32 znaki, użyty w całości, łącznie z prefiksem. Spośród własnych nagłówków easyCoexistence ustawia tylko Content-Type i ten jeden, bez nagłówka zdarzenia, więc nazwę zdarzenia odczytaj z 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))Co się dzieje, gdy sekret podpisu zostanie zastąpiony?
Nowy sekret podpisuje od następnego przekazania. Ponowne wywołanie set_social_webhook_destination lub PUT /channels/{id}/webhook zwraca świeży sekret i od razu wycofuje stary, a każde przekazanie wysyłane jest tylko raz, więc zdarzenie, które serwer odrzuci w czasie przełączania, przepada. Akceptuj oba sekrety przez kilka minut, podczas gdy nowy się wdraża. Zdarzenia statusu dotyczące kanałów i postów używają innego sekretu, tego z Dashboard, Profile, Developers, i przychodzą z nagłówkami X-EC-Event oraz X-EC-Delivery, ponawiane przez około 33 godziny.
Typowe błędy
- Weryfikowanie treści, którą framework już sparsował. Middleware JSON oddaje obiekt, a ponowna serializacja może zmienić bajty TikTok; czytaj surową treść na trasie webhooka.
- Odpowiadanie 200 na dostarczenie, którego podpis się nie zgodził. TikTok przestaje wysyłać zdarzenie, gdy zobaczy 200, więc prawdziwe zdarzenie odrzucone przez źle skonfigurowane sprawdzenie przepada; odpowiedź 4xx zostawia TikTok z ponawianiem przez do 72 godzin.
- Porównywanie podpisów operatorem ===, jak robi to przykład TikTok. Porównanie w stałym czasie, na przykład timingSafeEqual, nie ujawnia, ile fałszywego podpisu się zgadzało.
- Dekodowanie sekretu easyCoexistence z Base64 albo obcinanie prefiksu whsec_. Klucz HMAC to cały ciąg, dokładnie tak, jak został pokazany raz.
Ustaw endpoint przez set_social_webhook_destination z Claude lub ChatGPT albo przez PUT /channels/{id}/webhook. Od US$ 9 do US$ 0.75 za połączenie miesięcznie, im więcej połączeń, tym taniej, z pierwszymi 3 dniami za darmo.
Najczęściej zadawane pytania
Czym jest x-tt-logid w webhooku TikTok?
Nagłówkiem z unikalnym ID każdego dostarczenia. TikTok prosi odbiorców o jego zapisywanie, bo identyfikuje żądanie, gdy zgłaszasz problem TikTok.
Czy TikTok wysyła wyzwanie w celu weryfikacji nowego URL webhooka?
Nie, TikTok nie dokumentuje żadnego takiego wyzwania dla API for Business. Wywołanie /business/webhook/update/ rejestruje URL, a dostarczenia przychodzą wtedy z Tiktok-Signature, który Twój serwer sprawdza.
Dlaczego podpis webhooka TikTok nigdy się nie zgadza?
Sprawdź wejście i klucz: HMAC musi obejmować t, kropkę i surową treść w postaci otrzymanej, używać sekretu aplikacji i być porównany z wartością po s=, a nie z całym nagłówkiem.
Jak zweryfikować zdarzenia TikTok przekazane przez easyCoexistence?
Użyj nagłówka X-EC-Signature i sekretu podpisu, który pokazano przy ustawianiu miejsca docelowego: przelicz HMAC-SHA256 po t, kropce i surowej treści, porównaj z v1 i odrzuć t starsze niż 5 minut.
Czytaj dalej
Połącz pierwszy kanał w dwie minuty.
Bez czekania na weryfikację przez platformy. Połącz WhatsApp, Instagram, TikTok lub inny kanał, a potem poproś swoją AI o opublikowanie posta, odpowiedź lub raport i zobacz, jak działa.
- 3 dni za darmo
- Rezygnacja w każdej chwili
- Tylko oficjalne API
- Monitorowanie 24/7
Zweryfikowano w