Ρύθμιση των webhooks του TikTok API for Business
Το API for Business του TikTok στέλνει webhooks σε ένα callback URL ανά εφαρμογή και τύπο γεγονότος, που ορίζεται με POST /business/webhook/update/ χρησιμοποιώντας το app_id και το secret της εφαρμογής. Το event_type VIDEO εγγράφει τα τέσσερα γεγονότα δημοσίευσης ανάρτησης, και το COMMENT το comment.update. Κάθε αποστολή είναι ένα HTTPS POST υπογεγραμμένο στην κεφαλίδα Tiktok-Signature με HMAC-SHA256, με κλειδί το secret της εφαρμογής.
Το easyCoexistence διατηρεί εγγεγραμμένο για την εφαρμογή του το webhook σχολίων του TikTok, ελέγχει την υπογραφή του TikTok και προωθεί κάθε γεγονός σχολίου για τον λογαριασμό σας στο δικό σας HTTPS endpoint, υπογεγραμμένο με secret δικό του.
Πόσο χρόνο επαναδοκιμάζει το TikTok μια αποστολή που δεν απαντήθηκε με HTTP 200, με εκθετική καθυστέρηση, πριν την απορρίψει.
Τα περισσότερα post IDs που μπορεί να ονομάσει ένα item_list για να περιορίσει τα γεγονότα comment.update σε συγκεκριμένες αναρτήσεις.
Τρέχουσα τιμή της κεφαλίδας webhook-schema-version που στέλνει το TikTok με κάθε αποστολή.
Τι αναφέρει η αναφορά του TikTok για τα endpoints ρύθμισης του webhook, που πιστοποιούνται με το app ID και το secret.
Αλγόριθμος πίσω από το Tiktok-Signature: το timestamp, μια τελεία και το σώμα, με κλειδί το secret της εφαρμογής και κωδικοποίηση σε hex.
Άδεια εφαρμογής στο TikTok Accounts που απαιτείται για το comment.update· τα γεγονότα δημοσίευσης θέλουν Business Content.
Ποια γεγονότα webhook μπορεί να λάβει μια εφαρμογή λογαριασμού TikTok;
Δύο κατηγορίες, καθεμία εγγεγραμμένη ως δικός της event_type. Το VIDEO καλύπτει αναρτήσεις που δημοσιεύονται μέσω του /business/video/publish/ ή του /business/photo/publish/, και το COMMENT καλύπτει σχόλια στις φωτογραφίες και στα δημόσια βίντεο του λογαριασμού, είτε δημοσιεύτηκαν μέσω του API είτε στην εφαρμογή TikTok:
Τι χρειάζεται η εφαρμογή πριν την εγγραφή;
Πρόσβαση στο API for Business, μια εφαρμογή προγραμματιστή και λογαριασμοί TikTok που την έχουν εξουσιοδοτήσει. Ο οδηγός εγγραφής του TikTok προσθέτει μια άδεια για κάθε κατηγορία, και το γεγονός σχολίου χρειάζεται ένα scope από κάθε ιδιοκτήτη:
- Γεγονότα δημοσίευσης: η άδεια TikTok Accounts, Business Content στην εφαρμογή.
- Γεγονότα σχολίων: η άδεια TikTok Accounts, Business Comment στην εφαρμογή.
- comment.update: το scope comment.list, που χορηγεί ο ιδιοκτήτης και διατηρείται ενεργό.
- Ένα callback URL σε HTTPS που απαντά αμέσως με HTTP 200.
Πώς γίνεται η εγγραφή;
Με POST στο /business/webhook/update/, μία φορά για κάθε event_type. Το σώμα παίρνει app_id και secret, το event_type, VIDEO ή COMMENT, και callback_url· για το COMMENT μπορεί να πάρει και item_list. Η απάντηση επιστρέφει τα app_id, event_type, callback_url και, όταν έχει οριστεί, item_list. Νέα κλήση για το ίδιο event_type αντικαθιστά το callback URL.
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/business/webhook/update/' \
-H 'Content-Type: application/json' \
-d '{
"app_id": "<APP_ID>",
"secret": "<APP_SECRET>",
"event_type": "COMMENT",
"callback_url": "https://hooks.example.com/tiktok/"
}'
{
"code": 0,
"message": "OK",
"request_id": "<REQUEST_ID>",
"data": { "app_id": "<APP_ID>", "callback_url": "https://hooks.example.com/tiktok/", "event_type": "COMMENT" }
}Πώς το item_list περιορίζει τα γεγονότα σχολίων;
Περιορίζει το comment.update στις αναρτήσεις που ονομάζει, έως 100 IDs από το /business/video/list/, και η πρώτη λίστα ορίζει τη λειτουργία της εφαρμογής από τότε και μετά:
- Πρώτη κλήση COMMENT με
item_list: τα γεγονότα έρχονται μόνο για τις αναρτήσεις της λίστας. - Μεταγενέστερες κλήσεις με
item_list: οι νέες αναρτήσεις προστίθενται σε αυτές που ήδη υπάρχουν στη λίστα. - Κλήση COMMENT χωρίς
item_list, όταν δεν έχει οριστεί τίποτα πριν: τα γεγονότα έρχονται για τις αναρτήσεις των λογαριασμών που εξουσιοδότησαν την εφαρμογή. - Κλήση COMMENT χωρίς
item_list, όταν υπάρχει ήδη λίστα: οι ρυθμισμένες αναρτήσεις μένουν ως έχουν.
Πώς ελέγχεται ή αφαιρείται μια εγγραφή;
Το GET /business/webhook/list/ με app_id, secret και event_type επιστρέφει τη ρύθμιση: το callback_url εμφανίζεται μόνο όταν υπάρχει για αυτόν τον τύπο γεγονότος, και το item_list μόνο όταν έχει οριστεί. Το POST /business/webhook/delete/ με app_id, secret και event_type την αφαιρεί· για το COMMENT, ένα item_list στην κλήση διαγραφής αφαιρεί μόνο αυτές τις αναρτήσεις, ενώ χωρίς αυτό τα γεγονότα σχολίων σταματούν για όλες τις αναρτήσεις.
Τι πρέπει να κάνει το callback URL;
Να απαντά αμέσως. Το TikTok στέλνει JSON με POST μέσω HTTPS και θεωρεί αποτυχημένη κάθε αποστολή που δεν έχει απάντηση HTTP 200, επαναδοκιμάζοντας με εκθετική καθυστέρηση έως 72 ώρες πριν απορρίψει το γεγονός. Η παράδοση γίνεται τουλάχιστον μία φορά, οπότε το ίδιο γεγονός μπορεί να φτάσει δύο φορές και η επεξεργασία πρέπει να είναι idempotent. Κάθε αίτημα φέρει τρεις κεφαλίδες που αξίζει να καταγράφετε, tiktok-signature, webhook-schema-version και x-tt-logid, και σώμα με client_key, event, create_time σε δευτερόλεπτα, user_openid, που είναι το business_id του λογαριασμού, και content, μια σειριοποιημένη συμβολοσειρά JSON.
Πώς ελέγχεται το Tiktok-Signature;
Χωρίζετε την κεφαλίδα, t=<unix>,s=<hex>, σε κόμματα και μετά στο ίσον. Φτιάχνετε το υπογεγραμμένο μήνυμα από την τιμή του t, μια τελεία και το σώμα του αιτήματος, υπολογίζετε HMAC-SHA256 του με κλειδί το secret της εφαρμογής, το κωδικοποιείτε σε hex και το συγκρίνετε με το s. Μετά ελέγχετε την ηλικία του t: το TikTok υπογράφει τον χρόνο της αποστολής για να αποτρέψει τις επιθέσεις επανάληψης, και το δείγμα του δέχεται καθυστέρηση 5 δευτερολέπτων. Η χρήση του ακατέργαστου σώματος όπως λαμβάνεται αποφεύγει τη διαφορετική σειριοποίηση του JSON.
import hashlib, hmac, time
def verify_tiktok(raw_body: bytes, header: str, app_secret: str, max_age: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, s = parts.get("t", ""), parts.get("s", "")
if not t.isdigit():
return False
expected = hmac.new(app_secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, s) and abs(time.time() - int(t)) <= max_ageΠώς λαμβάνετε γεγονότα TikTok μέσω του easyCoexistence;
Ορίζοντας προορισμό για τον λογαριασμό. Το easyCoexistence διατηρεί τη δική του εφαρμογή εγγεγραμμένη στο COMMENT, ελέγχει την υπογραφή του TikTok, απαντά αμέσως στο TikTok και στέλνει κάθε comment.update για έναν συνδεδεμένο λογαριασμό στο HTTPS endpoint που έχει οριστεί για αυτόν. Από το Claude ή το ChatGPT, το set_social_webhook_destination δέχεται το account_id και ένα url, ή null για διακοπή, και επιστρέφει ένα signing secret που εμφανίζεται μόνο μία φορά· κάθε νέα κλήση εκδίδει καινούργιο. Τα γεγονότα δημοσίευσης δεν προωθούνται· το get_tiktok_publish_status παρακολουθεί μια ανάρτηση.
set_social_webhook_destination { "account_id": "<ACCOUNT_ID>", "url": "https://hooks.example.com/tiktok/" }
=> {
"url": "https://hooks.example.com/tiktok/",
"signing_secret": "whsec_<SECRET>",
"note": "Shown once: store it as a secret. ..."
}Πώς ρυθμίζεται με το Partner API;
Με PUT /channels/{id}/webhook στο https://easycoexistence.com/api/v1, με το κλειδί σας ec_live_ ως bearer token και σώμα {"url": "https://..."}. Η απάντηση περιέχει το webhook_url, το signing_secret και μια σημείωση, και το {"url": null} σταματά την προώθηση. Το URL πρέπει να χρησιμοποιεί HTTPS σε δημόσιο host· ένα άγνωστο κανάλι επιστρέφει 404 not_found, ένα αφαιρεμένο 409 removed και ένα σε αναστολή 402 suspended.
curl -X PUT "https://easycoexistence.com/api/v1/channels/$CHANNEL_ID/webhook" \
-H "Authorization: Bearer $EC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://hooks.example.com/tiktok/"}'
{ "webhook_url": "https://hooks.example.com/tiktok/", "signing_secret": "whsec_<SECRET>", "note": "..." }Πώς διαφέρουν οι δύο αποστολές;
Η προώθηση από το easyCoexistence υπογράφεται και διαμορφώνεται διαφορετικά από την παράδοση του ίδιου του TikTok, οπότε ένας παραλήπτης γραμμένος για τη μία χρειάζεται αλλαγές για την άλλη. Το προωθημένο payload κρατά τα πεδία σχολίου του TikTok, με το content αναλυμένο και τα IDs ως συμβολοσειρές· αυτό που αλλάζει είναι ο τρόπος υπογραφής, το εύρος και η επαναδοκιμή κάθε αποστολής:
| TikTok to your app | easyCoexistence to your endpoint | |
|---|---|---|
| Header | Tiktok-Signature: t=<unix>,s=<hex> | X-EC-Signature: t=<unix>,v1=<hex> |
| Key | The developer app's secret | The account's signing secret, shown once |
| Events | VIDEO and COMMENT, per app | comment.update, per connected account |
| Body | client_key, event, create_time, user_openid, content as a string | platform, account_id, external_id, entry with content parsed |
| Retries | Up to 72 hours | None: one attempt, 8 seconds, no redirects |
Πώς να το ρυθμίσετε
- Grant the permissionsGive the developer app Business Content for publishing events and Business Comment for comment events, and have owners grant comment.list.
- Build the callbackServe an HTTPS endpoint that checks Tiktok-Signature and replies 200 before doing any work.
- Subscribe each event typeCall /business/webhook/update/ with app_id, secret, event_type and callback_url, once for VIDEO and once for COMMENT.
- Confirm the configurationCall /business/webhook/list/ for each event_type and check that the callback_url, and any item_list, came back.
- Handle repeatsKey each event on its content, such as comment_id with comment_action, or publish_id with the event name, before acting on it.
Συνηθισμένα λάθη
- Επεξεργασία του γεγονότος πριν την απάντηση. Το TikTok ζητά άμεσο 200 και επαναδοκιμάζει αποστολές που δεν βλέπει επιβεβαιωμένες, οπότε βάλτε τη δουλειά σε ουρά και απαντήστε πρώτα.
- Αποστολή του item_list κατά λάθος στην πρώτη εγγραφή COMMENT. Από τότε και μετά, το TikTok αναφέρει γεγονότα σχολίων μόνο για τις αναρτήσεις της λίστας.
- Επαλήθευση με το access token. Το TikTok υπογράφει τα webhooks με το secret της εφαρμογής, το ίδιο που παίρνει το /business/webhook/update/.
- Σύνδεση δύο περιβαλλόντων στην ίδια εφαρμογή. Κάθε τύπος γεγονότος κρατά ένα callback_url ανά εφαρμογή, και μια νέα κλήση στο /business/webhook/update/ το αντικαθιστά.
Ορίστε το με το set_social_webhook_destination από το Claude ή το ChatGPT, ή με PUT /channels/{id}/webhook. Από US$ 9 έως US$ 0,75 ανά σύνδεση τον μήνα, με πτώση καθώς προσθέτετε συνδέσεις, και με τις πρώτες 3 ημέρες δωρεάν.
Συχνές ερωτήσεις
Ποιες κεφαλίδες φέρει μια αποστολή webhook του TikTok;
Το tiktok-signature, το webhook-schema-version, τρέχουσα τιμή v1.0, και το x-tt-logid, το ID της αποστολής. Το σώμα JSON περιέχει client_key, event, create_time, user_openid και content.
Στέλνει το TikTok webhook όταν δημοσιεύεται ένα βίντεο;
Ναι, με event_type VIDEO: post.publish.complete αφού το TikTok κατεβάσει και ελέγξει το αρχείο, και μετά post.publish.publicly_available, με το post_id, όταν η ανάρτηση γίνει δημόσια.
Πόσο καιρό επαναδοκιμάζει το TikTok ένα αποτυχημένο webhook;
Έως 72 ώρες με εκθετική καθυστέρηση, μετά τις οποίες το γεγονός απορρίπτεται. Η παράδοση γίνεται τουλάχιστον μία φορά, οπότε περιμένετε διπλότυπα.
Μπορώ να καταχωρίσω δικό μου callback στην εφαρμογή TikTok του easyCoexistence;
Όχι. Οι ρυθμίσεις webhook της εφαρμογής μένουν στο easyCoexistence. Το set_social_webhook_destination στέλνει αντί αυτού τα γεγονότα σχολίων του λογαριασμού σε εσάς.
Συνεχίστε την ανάγνωση
Συνδέστε το πρώτο σας κανάλι σε δύο λεπτά.
Χωρίς αναμονή για έλεγχο από τις πλατφόρμες. Συνδέστε WhatsApp, Instagram, TikTok ή άλλο κανάλι, ζητήστε από το AI σας να δημοσιεύσει, να απαντήσει ή να δημιουργήσει αναφορά και δείτε το να δουλεύει.
- 3 ημέρες δωρεάν
- Ακύρωση ανά πάσα στιγμή
- Μόνο επίσημα API
- Παρακολούθηση 24/7
Επαληθεύτηκε στις