Verifying TikTok webhooks: the signature header and how to check it
TikTok's API for Business signs each webhook delivery in a Tiktok-Signature header of the form t=<unix seconds>,s=<hex>, where s is an HMAC-SHA256 of the t value, a dot and the request body, keyed with the developer app's secret. To verify one, recompute that HMAC over the raw body as received, compare it with s in constant time and reject a stale t.
easyCoexistence checks TikTok's signature on each comment event its app receives, then forwards the connected account's comment events to your HTTPS endpoint, signed in X-EC-Signature with a secret for that account alone.
The two parts of Tiktok-Signature: the delivery's Unix timestamp in seconds and the signature TikTok generated for it.
The acceptableDelay in TikTok's Node sample, which refuses a correctly signed delivery older than that.
Header carrying each delivery's unique ID, which TikTok asks receivers to log for troubleshooting.
Event type for mention webhooks, whose subscription guide points to the same signature verification.
The signature part of easyCoexistence's X-EC-Signature header, an HMAC-SHA256 of t, a dot and the raw body.
What does the Tiktok-Signature header look like?
Two parts, separated by a comma: t, the Unix timestamp in seconds of that delivery, and s, the signature, 64 hexadecimal characters long. TikTok's pages write the name as TikTok-Signature, Tiktok-Signature and tiktok-signature; HTTP header names ignore case, so read it case-insensitively, as most frameworks already do. The other headers on 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: 202201120803530102451591650189C78Which bytes does TikTok sign?
The t value as a string, a full stop, then the body. TikTok's guide calls that last part a stringified JSON copy of the request body, and its Node sample rebuilds the copy by running JSON.stringify on an already parsed object. That reproduces TikTok's bytes only while both serializers agree on spacing, key order and escaping, so hash the body exactly as it arrived, before any JSON middleware reads it.
Which secret is the key?
The developer app's secret, found under My Apps, App Detail, Basic Information on TikTok's developer portal. It is the value the app already sends as secret to /business/webhook/update/ and as client_secret to the token endpoints. One secret signs the deliveries for each account that authorized the app, so a receiver needs no key per account, and neither the access token nor the app ID takes part.
How do you check it in Node.js?
With node:crypto and the raw body. The function below splits the header, recomputes the HMAC over t, the full stop and the body bytes, compares the result in constant time and then checks the age of t. It takes the name of the signature part as an argument, so the same code also checks easyCoexistence's forwards, where that part is called v1 and the key is the account's signing secret:
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
});How old can a delivery be before you refuse it?
TikTok leaves the cut-off to the receiver: compute the gap between your clock and t, its guide says, and decide whether it is tolerable. Its Node sample allows 5 seconds, tight enough that a server clock a few seconds off could refuse genuine deliveries; the code above allows 300, the window easyCoexistence asks receivers to use on its own forwards. Measure from t, the delivery time the signature covers, not from create_time in the body, which marks when the event occurred. In TikTok's sample, t falls one second after create_time.
What should the endpoint answer?
A 200 as soon as the signature checks out, with the work done afterwards, since TikTok treats any other status as a failed delivery and sends it again. For a signature that does not match, TikTok's sample answers with a 4xx status and logs the x-tt-logid header, which identifies the request if you report a problem to TikTok. client_key in the body names the developer app, so comparing it with your own app ID is a cheap second check.
How is the callback URL registered, and is it verified?
By one API call, and TikTok documents no challenge request that tests the URL first. POST /business/webhook/update/ takes the app_id, the secret, an event_type and an HTTPS callback_url: VIDEO for publishing events, COMMENT for comment.update and, on the Mentions API, BRAND_MENTION for brand.mention.event. All three arrive signed the same way, and GET /business/webhook/list/ shows the URL registered for an event type. The proof of origin is the signature on each delivery.
Can you check Tiktok-Signature on events easyCoexistence forwards?
No, and nothing calls for it. TikTok signs those deliveries with the secret of easyCoexistence's own developer app, which no tool or API hands out. easyCoexistence checks that signature as each event arrives, answers 401 to one that fails, ignores a body whose client_key names another app, and then signs its forward to you in X-EC-Signature with the signing secret of that connected account.
How does easyCoexistence sign what it forwards?
In the X-EC-Signature header, t=<unix>,v1=<hex>, where t is the time of the forward and v1 the hex HMAC-SHA256 of t, a full stop and the body exactly as sent. The key is the account's signing secret, whsec_ followed by 32 characters, used whole, prefix included. Of its own headers, easyCoexistence sets only Content-Type and this one, with no event header, so read the event's name from 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))What happens when the signing secret is replaced?
The new secret signs from the next forward on. Calling set_social_webhook_destination or PUT /channels/{id}/webhook again returns a fresh secret and retires the old one at once, and each forward is sent a single time, so an event your server refuses during the switch is lost. Accept both secrets for a few minutes while the new one deploys. Status events about channels and posts use another secret, the one from Dashboard, Profile, Developers, and arrive with X-EC-Event and X-EC-Delivery headers, retried for about 33 hours.
Common mistakes
- Verifying a body the framework already parsed. JSON middleware hands over an object, and serializing it again can change TikTok's bytes; read the raw body on the webhook route.
- Answering 200 to a delivery whose signature failed. TikTok stops sending an event once it sees a 200, so a genuine one refused by a misconfigured check is lost; a 4xx leaves TikTok retrying for up to 72 hours.
- Comparing signatures with ===, as TikTok's sample does. A constant-time comparison such as timingSafeEqual does not reveal how much of a forged signature matched.
- Base64-decoding easyCoexistence's secret or cutting off its whsec_ prefix. The HMAC key is the whole string, exactly as it was shown once.
Set the endpoint with set_social_webhook_destination from Claude or ChatGPT, or with PUT /channels/{id}/webhook. US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.
easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.
Frequently asked questions
What is x-tt-logid in a TikTok webhook?
A header carrying each delivery's unique ID. TikTok asks receivers to log it, since it identifies the request when you report a problem to TikTok.
Does TikTok send a challenge to verify a new webhook URL?
TikTok documents none for its API for Business. The /business/webhook/update/ call registers the URL, and deliveries then arrive with Tiktok-Signature for your server to check.
Why does my TikTok webhook signature never match?
Check the input and the key: the HMAC must cover t, a full stop and the raw body as received, use the app secret, and be compared with the value after s= rather than the whole header.
How do I verify TikTok events forwarded by easyCoexistence?
With X-EC-Signature and the signing secret shown when you set the destination: recompute HMAC-SHA256 over t, a full stop and the raw body, compare it with v1, and refuse a t over 5 minutes old.
Keep reading
Connect your first channel in two minutes.
No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.
- 3 days free
- Cancel any time
- Official APIs only
- Monitored 24/7
Verified on