Επαλήθευση webhooks του TikTok: η κεφαλίδα υπογραφής και ο τρόπος ελέγχου της
Το API for Business του TikTok υπογράφει κάθε παράδοση webhook σε μια κεφαλίδα Tiktok-Signature της μορφής t=<unix seconds>,s=<hex>, όπου το s είναι ένα HMAC-SHA256 της τιμής t, μιας τελείας και του σώματος του αιτήματος, με κλειδί το μυστικό της εφαρμογής προγραμματιστή. Για να την επαληθεύσετε, υπολογίστε ξανά το HMAC πάνω στο ακατέργαστο σώμα όπως ελήφθη, συγκρίνετέ το με το s σε σταθερό χρόνο και απορρίψτε μια παλιά τιμή t.
Το easyCoexistence ελέγχει την υπογραφή του TikTok σε κάθε γεγονός σχολίου που λαμβάνει η εφαρμογή του, και έπειτα προωθεί τα γεγονότα σχολίων του συνδεδεμένου λογαριασμού στο HTTPS endpoint σας, υπογεγραμμένα στην X-EC-Signature με μυστικό μόνο για εκείνον τον λογαριασμό.
Τα δύο μέρη της Tiktok-Signature: το Unix timestamp της παράδοσης σε δευτερόλεπτα και η υπογραφή που δημιούργησε το TikTok για αυτήν.
Το acceptableDelay στο δείγμα Node.js του TikTok, που απορρίπτει μια σωστά υπογεγραμμένη παράδοση παλαιότερη από αυτό.
Κεφαλίδα που μεταφέρει το μοναδικό ID κάθε παράδοσης, το οποίο το TikTok ζητά από τους παραλήπτες να καταγράφουν για αντιμετώπιση προβλημάτων.
Τύπος γεγονότος για τα webhooks αναφορών, του οποίου ο οδηγός συνδρομής παραπέμπει στην ίδια επαλήθευση υπογραφής.
Το τμήμα υπογραφής της κεφαλίδας X-EC-Signature του easyCoexistence, ένα HMAC-SHA256 της τιμής t, μιας τελείας και του ακατέργαστου σώματος.
Πώς είναι η κεφαλίδα Tiktok-Signature;
Δύο μέρη, χωρισμένα με κόμμα: το t, το Unix timestamp σε δευτερόλεπτα της συγκεκριμένης παράδοσης, και το s, η υπογραφή, μήκους 64 δεκαεξαδικών χαρακτήρων. Οι σελίδες του TikTok γράφουν το όνομα ως TikTok-Signature, Tiktok-Signature και tiktok-signature. Τα ονόματα κεφαλίδων HTTP δεν διακρίνουν πεζά και κεφαλαία, οπότε διαβάστε την χωρίς διάκριση, όπως ήδη κάνουν τα περισσότερα frameworks. Οι υπόλοιπες κεφαλίδες του δείγματος παράδοσης του 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 string του σώματος του αιτήματος, και το δείγμα Node.js ξαναδημιουργεί το αντίγραφο εκτελώντας JSON.stringify σε ένα ήδη αναλυμένο αντικείμενο. Αυτό αναπαράγει τα bytes του TikTok μόνο εφόσον και οι δύο σειριοποιητές συμφωνούν στα κενά, τη σειρά των κλειδιών και τη διαφυγή χαρακτήρων. Γι' αυτό υπολογίστε την υπογραφή πάνω στο σώμα ακριβώς όπως έφτασε, πριν το διαβάσει οποιοδήποτε JSON middleware.
Ποιο μυστικό είναι το κλειδί;
Το μυστικό της εφαρμογής προγραμματιστή, που βρίσκεται στο My Apps, App Detail, Basic Information στην πύλη προγραμματιστή του TikTok. Είναι η τιμή που η εφαρμογή ήδη στέλνει ως secret στο /business/webhook/update/ και ως client_secret στα endpoints για το token. Ένα μυστικό υπογράφει τις παραδόσεις για κάθε λογαριασμό που εξουσιοδότησε την εφαρμογή, οπότε ο παραλήπτης δεν χρειάζεται κλειδί ανά λογαριασμό, και ούτε το access token ούτε το app ID συμμετέχουν.
Πώς ελέγχεται στο Node.js;
Με το node:crypto και το ακατέργαστο σώμα. Η συνάρτηση παρακάτω χωρίζει την κεφαλίδα, υπολογίζει ξανά το HMAC πάνω στο t, την τελεία και τα bytes του σώματος, συγκρίνει το αποτέλεσμα σε σταθερό χρόνο και μετά ελέγχει την ηλικία του 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 δευτερόλεπτα, αρκετά στενό ώστε ένας server με ρολόι που αποκλίνει λίγα δευτερόλεπτα να απορρίψει γνήσιες παραδόσεις. Ο κώδικας παραπάνω επιτρέπει 300, το παράθυρο που το easyCoexistence ζητά από τους παραλήπτες για τις δικές του προωθήσεις. Μετρήστε από το t, τη στιγμή της παράδοσης που καλύπτει η υπογραφή, όχι από το create_time στο σώμα, που σημαίνει πότε συνέβη το γεγονός. Στο δείγμα του TikTok, το t είναι ένα δευτερόλεπτο μετά το create_time.
Τι πρέπει να απαντά το endpoint;
Ένα 200 μόλις η υπογραφή επαληθευτεί, με τη δουλειά να γίνεται μετά, αφού το TikTok θεωρεί κάθε άλλη κατάσταση αποτυχημένη παράδοση και την στέλνει ξανά. Για υπογραφή που δεν ταιριάζει, το δείγμα του TikTok απαντά με κατάσταση 4xx και καταγράφει την κεφαλίδα x-tt-logid, που ταυτοποιεί το αίτημα αν αναφέρετε πρόβλημα στο TikTok. Το client_key στο σώμα ονομάζει την εφαρμογή προγραμματιστή, οπότε η σύγκρισή του με το δικό σας app 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 επιστρέφει νέο μυστικό και αποσύρει το παλιό αμέσως. Κάθε προώθηση στέλνεται μία μόνο φορά, οπότε ένα γεγονός που ο server σας απορρίπτει κατά την αλλαγή χάνεται. Δεχτείτε και τα δύο μυστικά για λίγα λεπτά, όσο αναπτύσσεται το νέο. Τα γεγονότα κατάστασης για κανάλια και δημοσιεύσεις χρησιμοποιούν άλλο μυστικό, αυτό από το Dashboard, Profile, Developers, και φτάνουν με κεφαλίδες X-EC-Event και X-EC-Delivery, με επαναδοκιμές για περίπου 33 ώρες.
Συνηθισμένα λάθη
- Επαλήθευση σώματος που το framework έχει ήδη αναλύσει. Το JSON middleware παραδίδει ένα αντικείμενο, και η εκ νέου σειριοποίησή του μπορεί να αλλάξει τα bytes του TikTok. Διαβάστε το ακατέργαστο σώμα στη διαδρομή του webhook.
- Απάντηση 200 σε παράδοση της οποίας η υπογραφή απέτυχε. Το TikTok σταματά να στέλνει ένα γεγονός μόλις δει 200, οπότε ένα γνήσιο γεγονός που απορρίφθηκε από λανθασμένο έλεγχο χάνεται. Ένα 4xx αφήνει το TikTok να επαναδοκιμάζει έως και 72 ώρες.
- Σύγκριση των υπογραφών με ===, όπως κάνει το δείγμα του TikTok. Η σύγκριση σε σταθερό χρόνο, όπως το timingSafeEqual, δεν αποκαλύπτει πόσο ταίριαξε μια πλαστή υπογραφή.
- Αποκωδικοποίηση base64 του μυστικού του easyCoexistence ή αποκοπή του προθέματος whsec_. Το κλειδί HMAC είναι ολόκληρη η συμβολοσειρά, ακριβώς όπως εμφανίστηκε μία φορά.
Ρυθμίστε το endpoint με το set_social_webhook_destination από το Claude ή το ChatGPT, ή με το PUT /channels/{id}/webhook. Από US$ 9 έως US$ 0,75 ανά σύνδεση τον μήνα, με μείωση όσο προσθέτετε συνδέσεις, και με τις πρώτες 3 ημέρες δωρεάν.
Συχνές ερωτήσεις
Τι είναι το x-tt-logid σε ένα webhook του TikTok;
Κεφαλίδα που μεταφέρει το μοναδικό ID κάθε παράδοσης. Το TikTok ζητά από τους παραλήπτες να το καταγράφουν, γιατί ταυτοποιεί το αίτημα όταν αναφέρετε πρόβλημα στο TikTok.
Στέλνει το TikTok πρόκληση για να επαληθεύσει νέο URL webhook;
Το TikTok δεν τεκμηριώνει καμία για το API for Business του. Η κλήση /business/webhook/update/ καταχωρίζει το URL, και οι παραδόσεις φτάνουν έπειτα με Tiktok-Signature για να την ελέγξει ο server σας.
Γιατί η υπογραφή του webhook TikTok δεν ταιριάζει ποτέ;
Ελέγξτε την είσοδο και το κλειδί: το HMAC πρέπει να καλύπτει το t, μια τελεία και το ακατέργαστο σώμα όπως ελήφθη, να χρησιμοποιεί το μυστικό της εφαρμογής και να συγκρίνεται με την τιμή μετά το s=, όχι με ολόκληρη την κεφαλίδα.
Πώς επαληθεύω γεγονότα του TikTok που προωθεί το easyCoexistence;
Με το X-EC-Signature και το μυστικό υπογραφής που εμφανίστηκε όταν ορίσατε τον προορισμό: υπολογίστε ξανά το HMAC-SHA256 πάνω στο t, μια τελεία και το ακατέργαστο σώμα, συγκρίνετέ το με το v1 και απορρίψτε t παλαιότερο από 5 λεπτά.
Συνεχίστε την ανάγνωση
Συνδέστε το πρώτο σας κανάλι σε δύο λεπτά.
Χωρίς αναμονή για έλεγχο από τις πλατφόρμες. Συνδέστε WhatsApp, Instagram, TikTok ή άλλο κανάλι, ζητήστε από το AI σας να δημοσιεύσει, να απαντήσει ή να δημιουργήσει αναφορά και δείτε το να δουλεύει.
- 3 ημέρες δωρεάν
- Ακύρωση ανά πάσα στιγμή
- Μόνο επίσημα API
- Παρακολούθηση 24/7
Επαληθεύτηκε στις