Giriş yapınÜcretsiz denemeyi başlatın
easyCoexistence Resmi API'ler

TikTok webhook'larını doğrulama: imza başlığı ve nasıl kontrol edilir

TikTok API for Business her webhook teslimatını Tiktok-Signature başlığında imzalar; başlık t=<unix saniye>,s=<hex> biçimindedir. Burada s, t değerinin, bir noktanın ve istek gövdesinin, geliştirici uygulamasının sırrıyla anahtarlanmış HMAC-SHA256'sıdır. Doğrulamak için ham gövde üzerinden HMAC'i yeniden hesaplayın, s ile sabit zamanda karşılaştırın ve eski bir t değerini reddedin.

easyCoexistence, uygulamasının aldığı her yorum olayında TikTok imzasını kontrol eder, ardından bağlı hesabın yorum olaylarını HTTPS uç noktanıza iletir; bu iletim yalnızca o hesaba ait bir sırla X-EC-Signature içinde imzalanır.

t and s

Tiktok-Signature'ın iki parçası: teslimatın saniye cinsinden Unix zaman damgası ve TikTok'un bunun için ürettiği imza.

5 seconds

TikTok'un Node örneğindeki acceptableDelay, bu süreden eski olan doğru imzalı bir teslimatı reddeder.

x-tt-logid

Her teslimatın benzersiz kimliğini taşıyan başlık; TikTok, sorun giderme için alıcıların bunu kaydetmesini ister.

BRAND_MENTION

Bahsetme webhook'ları için olay türü; abonelik kılavuzu aynı imza doğrulamasına yönlendirir.

v1

easyCoexistence'ın X-EC-Signature başlığının imza kısmı: t, nokta ve ham gövdenin HMAC-SHA256'sı.

Tiktok-Signature başlığı nasıl görünür?

Virgülle ayrılmış iki parçadan oluşur: t, o teslimatın saniye cinsinden Unix zaman damgası; s, 64 onaltılık karakter uzunluğunda imza. TikTok'un sayfaları adı TikTok-Signature, Tiktok-Signature ve tiktok-signature olarak yazar; HTTP başlık adları büyük-küçük harfe duyarsızdır, bu yüzden çoğu çatının zaten yaptığı gibi büyük-küçük harfe duyarsız okuyun. TikTok'un örnek teslimatındaki diğer başlıklar:

Headers from 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: 202201120803530102451591650189C78

TikTok hangi baytları imzalar?

t değerini dize olarak, bir nokta ve ardından gövdeyi. TikTok'un kılavuzu son kısmı istek gövdesinin dizeleştirilmiş JSON kopyası olarak adlandırır; Node örneği ise zaten ayrıştırılmış bir nesneye JSON.stringify uygulayarak bu kopyayı yeniden oluşturur. Bu yöntem, iki serileştiricinin boşluk, anahtar sırası ve kaçış karakterleri konusunda aynı fikirde olduğu sürece TikTok'un baytlarını yeniden üretir; bu yüzden gövdeyi geldiği gibi, herhangi bir JSON ara katmanı onu okumadan önce özetleyin.

Anahtar hangi sır?

Geliştirici uygulamasının sırrı; TikTok'un geliştirici portalında My Apps, App Detail, Basic Information altında bulunur. Uygulamanın /business/webhook/update/ adresine secret olarak, token uç noktalarına ise client_secret olarak zaten gönderdiği değerdir. Tek bir sır, uygulamayı yetkilendiren her hesabın teslimatlarını imzalar; bu yüzden alıcının hesap başına anahtara ihtiyacı yoktur ve erişim token'ı ile uygulama kimliği bu işe katılmaz.

Node.js'te nasıl kontrol edersiniz?

node:crypto ve ham gövdeyle. Aşağıdaki fonksiyon başlığı böler, t, nokta ve gövde baytları üzerinden HMAC'i yeniden hesaplar, sonucu sabit zamanda karşılaştırır, ardından t'nin yaşını kontrol eder. İmza kısmının adını argüman olarak alır; böylece aynı kod easyCoexistence'ın iletimlerini de kontrol eder. Orada bu kısım v1 olarak adlandırılır ve anahtar hesabın imzalama sırrıdır:

Node.js and Express: TikTok's deliveries and easyCoexistence's forwards
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
});

Bir teslimat ne kadar eski olabilir ve ne zaman reddedersiniz?

Sınırı TikTok alıcıya bırakır: kılavuzuna göre saatiniz ile t arasındaki farkı hesaplayın ve bunun tolere edilebilir olup olmadığına karar verin. Node örneği 5 saniye tanır; bu kadar sıkı bir sınır, saati birkaç saniye şaşan bir sunucunun gerçek teslimatları reddetmesine yol açabilir. Yukarıdaki kod ise easyCoexistence'ın kendi iletimlerinde alıcılardan kullanmalarını istediği pencere olan 300 saniyeye izin verir. Yaşı, gövdedeki create_time'dan değil, imzanın kapsadığı teslimat zamanı olan t'den ölçün; create_time olayın gerçekleştiği anı işaretler. TikTok'un örneğinde t, create_time'dan bir saniye sonra gelir.

Uç nokta ne yanıtlamalı?

İmza doğrulandığında hemen 200, iş ise sonradan yapılır; çünkü TikTok diğer her durum kodunu başarısız teslimat sayar ve yeniden gönderir. Eşleşmeyen bir imza için TikTok'un örneği 4xx durumu döndürür ve x-tt-logid başlığını kaydeder; bu başlık, TikTok'a bir sorun bildirirken isteği tanımlar. Gövdedeki client_key, geliştirici uygulamasının adını taşır; bunu kendi uygulama kimliğinizle karşılaştırmak hafif bir ikinci kontroldür.

Geri çağrı URL'si nasıl kaydedilir ve doğrulanır mı?

Tek bir API çağrısıyla; TikTok, URL'yi önce test eden bir challenge isteği belgelemez. POST /business/webhook/update/ app_id, secret, bir event_type ve HTTPS callback_url alır: yayınlama olayları için VIDEO, comment.update için COMMENT ve Mentions API'de brand.mention.event için BRAND_MENTION. Üçü de aynı şekilde imzalanarak gelir; GET /business/webhook/list/ her olay türü için kayıtlı URL'yi gösterir. Kökenin kanıtı, her teslimattaki imzadır.

easyCoexistence'ın ilettiği olaylarda Tiktok-Signature kontrol edilebilir mi?

Hayır, buna gerek yok. TikTok bu teslimatları easyCoexistence'ın kendi geliştirici uygulamasının sırrıyla imzalar; bu sır hiçbir araç veya API tarafından verilmez. easyCoexistence her olay geldiğinde TikTok imzasını kontrol eder, başarısız olana 401 yanıtı verir, gövdedeki client_key başka bir uygulamayı gösteriyorsa olayı yok sayar ve ardından size iletimini, bağlı o hesabın imzalama sırrıyla X-EC-Signature içinde imzalar.

easyCoexistence ilettiklerini nasıl imzalar?

X-EC-Signature başlığında: t=<unix>,v1=<hex>; burada t iletimin zamanı, v1 ise t, bir nokta ve gövdenin tam gönderildiği haliyle onaltılık HMAC-SHA256'dır. Anahtar, hesabın imzalama sırrıdır; whsec_ ile başlayan ve ardından 32 karakter gelen değer, önek dahil olmak üzere bütün olarak kullanılır. easyCoexistence kendi başlıklarından yalnızca Content-Type ve bu başlığı ayarlar, olay başlığı yoktur; bu yüzden olayın adını entry.event alanından okuyun:

A forwarded TikTok comment event, as sent
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))

İmzalama sırrı değiştirildiğinde ne olur?

Yeni sır bir sonraki iletimden itibaren imzalar. set_social_webhook_destination çağrısı veya PUT /channels/{id}/webhook yeniden çağrıldığında yeni bir sır döner ve eskisi hemen emekliye ayrılır; her iletim yalnızca bir kez gönderildiği için geçiş sırasında sunucunuzun reddettiği bir olay kaybolur. Yeni sır devreye girerken birkaç dakika boyunca her iki sırrı da kabul edin. Kanallar ve gönderiler hakkındaki durum olayları başka bir sır kullanır; bu sır Panel, Profil, Geliştiriciler bölümündedir ve X-EC-Event ile X-EC-Delivery başlıklarıyla gelir; yaklaşık 33 saat boyunca yeniden denenir.

Yaygın hatalar

  • Framework'ün zaten ayrıştırdığı gövdeyi doğrulamak. JSON ara katmanı bir nesne verir ve onu yeniden serileştirmek TikTok'un baytlarını değiştirebilir; ham gövdeyi webhook rotasında okuyun.
  • İmzası başarısız olan bir teslimata 200 yanıtı vermek. TikTok bir 200 gördüğünde bir olayı göndermeyi durdurur; bu yüzden yanlış yapılandırılmış bir kontrol nedeniyle reddedilen gerçek bir olay kaybolur. 4xx yanıtı ise TikTok'un 72 saate kadar yeniden denemesine yol açar.
  • İmzaları, TikTok'un örneğinin yaptığı gibi === ile karşılaştırmak. timingSafeEqual gibi sabit zamanlı bir karşılaştırma, sahte bir imzanın ne kadarının eşleştiğini ortaya çıkarmaz.
  • easyCoexistence'ın sırrını Base64 ile çözmek ya da whsec_ önekini kesmek. HMAC anahtarı, bir kez gösterildiği haliyle bütün dizedir.
Bunu EasyCoexistence'la yapmak

Uç noktayı Claude veya ChatGPT'den set_social_webhook_destination ile ya da PUT /channels/{id}/webhook ile ayarlayın. Bağlantı başına aylık US$ 9'dan US$ 0.75'e kadar, bağlantı ekledikçe düşen fiyatla; ilk 3 gün ücretsiz deneme.

Sık sorulan sorular

x-tt-logid, TikTok webhook'unda nedir?

Her teslimatın benzersiz kimliğini taşıyan bir başlık. TikTok, sorun bildirirken isteği tanımladığı için alıcıların bunu kaydetmesini ister.

TikTok yeni bir webhook URL'sini doğrulamak için challenge gönderir mi?

TikTok, API for Business için böyle bir istek belgelemez. /business/webhook/update/ çağrısı URL'yi kaydeder; teslimatlar bundan sonra sunucunuzun kontrol edeceği Tiktok-Signature ile gelir.

TikTok webhook imzam neden hiç eşleşmiyor?

Girdiyi ve anahtarı kontrol edin: HMAC, t, bir nokta ve ham gövdeyi geldiği haliyle kapsamalı, uygulama sırrını kullanmalı ve tüm başlık yerine s= sonrasındaki değerle karşılaştırılmalıdır.

easyCoexistence'ın ilettiği TikTok olaylarını nasıl doğrularım?

X-EC-Signature ve hedefi ayarlarken gösterilen imzalama sırrıyla: t, bir nokta ve ham gövde üzerinden HMAC-SHA256'yı yeniden hesaplayın, v1 ile karşılaştırın ve 5 dakikadan eski bir t'yi reddedin.

Okumaya devam edin

İlk kanalınızı iki dakikada bağlayın.

Beklemeniz gereken platform incelemesi yok. WhatsApp, Instagram, TikTok veya başka bir kanalı bağlayın, ardından yapay zekânızdan paylaşım yapmasını, yanıtlamasını ya da rapor vermesini isteyin ve işini izleyin.

  • 3 gün ücretsiz
  • İstediğiniz zaman iptal
  • Yalnızca resmi API'ler
  • 7/24 izleniyor

Doğrulama tarihi