Проверка вебхуков TikTok: заголовок подписи и как его проверить
API for Business у TikTok подписывает каждую доставку вебхука в заголовке Tiktok-Signature вида t=<unix seconds>,s=<hex>, где s является HMAC-SHA256 от значения t, точки и тела запроса, ключом служит секрет приложения разработчика. Чтобы проверить подпись, пересчитайте HMAC по сырому телу в том виде, в каком оно пришло, сравните с s за постоянное время и отклоните устаревший t.
EasyCoexistence проверяет подпись TikTok на каждом событии комментария, которое получает его приложение, затем пересылает события комментариев подключённого аккаунта на ваш HTTPS-эндпоинт, подписанные в X-EC-Signature секретом только для этого аккаунта.
Две части Tiktok-Signature: временная метка Unix доставки в секундах и подпись, которую TikTok сформировал для неё.
acceptableDelay в примере TikTok на Node.js: он отклоняет правильно подписанную доставку, если она старше этого значения.
Заголовок, который несёт уникальный ID каждой доставки; TikTok просит получателей записывать его для поиска неисправностей.
Тип события для вебхуков упоминаний; в руководстве по подписке на них ссылаются на ту же проверку подписи.
Часть подписи заголовка X-EC-Signature в EasyCoexistence: HMAC-SHA256 от t, точки и сырого тела.
Как выглядит заголовок Tiktok-Signature?
Две части через запятую: t, временная метка Unix в секундах для этой доставки, и s, подпись длиной 64 шестнадцатеричных символа. На страницах TikTok имя пишут как TikTok-Signature, Tiktok-Signature и tiktok-signature; имена HTTP-заголовков не чувствительны к регистру, поэтому читайте его без учёта регистра, как и большинство фреймворков. Остальные заголовки в примере доставки 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: 202201120803530102451591650189C78Какие байты подписывает TikTok?
Значение t как строку, точку, затем тело. В руководстве TikTok эта последняя часть названа строковой копией тела запроса в JSON, а пример на Node.js воссоздаёт копию, вызывая JSON.stringify над уже разобранным объектом. Это воспроизводит байты TikTok, только пока оба сериализатора совпадают в пробелах, порядке ключей и экранировании, поэтому хешируйте тело ровно так, как оно пришло, до того как его прочитает любое JSON-промежуточное ПО.
Какой секрет служит ключом?
Секрет приложения разработчика, его находят в разделах «My Apps», «App Detail», «Basic Information» на портале разработчиков TikTok. Это то значение, которое приложение уже передаёт как поле secret в /business/webhook/update/ и как client_secret в эндпоинты выдачи токенов. Один секрет подписывает доставки для каждого аккаунта, который авторизовал приложение, поэтому получателю не нужен ключ для каждого аккаунта, и ни токен доступа, ни ID приложения в подписи не участвуют.
Как проверить подпись в Node.js?
С помощью node:crypto и сырого тела. Функция ниже разбивает заголовок, пересчитывает HMAC от t, точки и байтов тела, сравнивает результат за постоянное время, затем проверяет возраст t. Имя части подписи передаётся аргументом, поэтому тот же код проверяет и пересылки EasyCoexistence, где эта часть называется v1, а ключом служит секрет подписи аккаунта:
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
});Насколько старой может быть доставка, прежде чем её отклонить?
TikTok оставляет границу получателю: вычислите разницу между вашими часами и t, как сказано в руководстве, и решите, допустима ли она. Пример на Node.js допускает 5 секунд, что так тесно, что сервер с часами, сбитыми на несколько секунд, может отклонить настоящие доставки; код выше допускает 300, окно, которое EasyCoexistence просит получателей использовать для своих пересылок. Отсчитывайте от t, момента доставки, который покрывает подпись, а не от create_time в теле, где отмечен момент наступления события. В примере TikTok t наступает через одну секунду после create_time.
Что должен возвращать эндпоинт?
200 сразу, как только подпись сошлась, а работу выполнять после, поскольку TikTok считает любой другой статус неудачной доставкой и посылает её снова. Для несовпадающей подписи пример TikTok отвечает статусом 4xx и записывает заголовок x-tt-logid, который определяет запрос, если вы сообщаете TikTok о проблеме. Поле client_key в теле называет приложение разработчика, поэтому сравнение его с вашим ID приложения служит недорогой второй проверкой.
Как регистрируется URL обратного вызова и проверяется ли он?
Одним вызовом API, и TikTok не документирует проверочного запроса, который сначала тестирует URL. POST /business/webhook/update/ принимает app_id, secret, event_type и HTTPS-адрес callback_url: VIDEO для событий публикаций, COMMENT для comment.update и, в Mentions API, BRAND_MENTION для brand.mention.event. Все три приходят подписанными одинаково, а GET /business/webhook/list/ показывает URL, зарегистрированный для типа события. Подтверждением происхождения служит подпись каждой доставки.
Можно ли проверять Tiktok-Signature в событиях, которые пересылает EasyCoexistence?
Нет, и это не требуется. TikTok подписывает эти доставки секретом собственного приложения разработчика EasyCoexistence, который не выдаёт ни один инструмент или API. EasyCoexistence проверяет эту подпись при поступлении каждого события, отвечает 401 на неудачную, игнорирует тело, в котором client_key называет другое приложение, и затем подписывает свою пересылку вам в X-EC-Signature секретом подписи того подключённого аккаунта.
Как EasyCoexistence подписывает то, что пересылает?
В заголовке X-EC-Signature: t=<unix>,v1=<hex>, где t это время пересылки, а v1 шестнадцатеричный HMAC-SHA256 от t, точки и тела ровно в том виде, в каком оно отправлено. Ключом служит секрет подписи аккаунта, то есть whsec_ и 32 символа после него, используемые целиком, с префиксом. Из своих заголовков EasyCoexistence ставит только Content-Type и этот, без заголовка события, поэтому имя события читайте из 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))Что происходит при замене секрета подписи?
Новый секрет подписывает со следующей пересылки. Повторный вызов set_social_webhook_destination или PUT /channels/{id}/webhook возвращает свежий секрет и сразу отзывает старый, а каждая пересылка отправляется один раз, поэтому событие, которое ваш сервер отклонит во время переключения, будет потеряно. Принимайте оба секрета несколько минут, пока разворачивается новый. События статуса по каналам и публикациям используют другой секрет, тот, что показан в панели управления, в разделе «Профиль», затем «Разработчики»; они приходят с заголовками X-EC-Event и X-EC-Delivery и повторно отправляются примерно 33 часа.
Распространённые ошибки
- Проверка тела, которое фреймворк уже разобрал. JSON-промежуточное ПО отдаёт объект, и повторная сериализация может изменить байты TikTok; читайте сырое тело на маршруте вебхука.
- Ответ 200 на доставку, у которой подпись не сошлась. TikTok перестаёт слать событие, как только видит 200, поэтому настоящее событие, отклонённое ошибочной проверкой, теряется; статус 4xx заставляет TikTok повторять попытки до 72 часов.
- Сравнение подписей через ===, как в примере TikTok. Сравнение за постоянное время, например timingSafeEqual, не раскрывает, сколько символов поддельной подписи совпало.
- Декодирование секрета EasyCoexistence из base64 или отрезание префикса whsec_. Ключ HMAC это вся строка целиком, в точности как её показали один раз.
Задайте эндпоинт через set_social_webhook_destination из Claude или ChatGPT либо через PUT /channels/{id}/webhook. От US$ 9 до US$ 0,75 за подключение в месяц, цена снижается по мере добавления подключений, с бесплатным пробным периодом на первые 3 дня.
Часто задаваемые вопросы
Что такое x-tt-logid в вебхуке TikTok?
Заголовок с уникальным ID каждой доставки. TikTok просит получателей его записывать, так как он определяет запрос, когда вы сообщаете TikTok о проблеме.
Отправляет ли TikTok проверочный запрос для проверки нового URL вебхука?
Для своего API for Business TikTok такого не документирует. Вызов /business/webhook/update/ регистрирует URL, а доставки затем приходят с Tiktok-Signature, которую ваш сервер проверяет.
Почему подпись вебхука TikTok никогда не совпадает?
Проверьте вход и ключ: HMAC должен покрывать t, точку и сырое тело в том виде, в каком оно пришло, использовать секрет приложения и сравниваться со значением после s=, а не со всем заголовком.
Как проверить события TikTok, которые пересылает EasyCoexistence?
С X-EC-Signature и секретом подписи, показанным при задании адреса назначения: пересчитайте HMAC-SHA256 от t, точки и сырого тела, сравните с v1 и отклоните t старше 5 минут.
Читайте дальше
Подключите первый канал за две минуты.
Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.
- 3 дня бесплатно
- Отмена в любой момент
- Только официальные API
- Мониторинг 24/7
Проверено по состоянию на