Kirjaudu sisäänAloita ilmainen kokeilu
easyCoexistence Viralliset API:t

TikTok-webhookien vahvistaminen: allekirjoitusotsake ja sen tarkistaminen

TikTokin API for Business allekirjoittaa jokaisen webhook-toimituksen Tiktok-Signature-otsakkeessa muodossa t=<unix-sekunnit>,s=<hex>, missä s on HMAC-SHA256 t-arvosta, pisteestä ja pyynnön rungosta, avaimena kehittäjäsovelluksen salaisuus. Vahvistaaksesi toimituksen laske HMAC uudelleen vastaanotetusta raakarungosta, vertaa sitä s-arvoon vakioaikaisella vertailulla ja hylkää vanhentunut t.

easyCoexistence tarkistaa TikTokin allekirjoituksen jokaisesta sen sovelluksen vastaanottamasta kommenttitapahtumasta ja välittää yhdistetyn tilin kommenttitapahtumat HTTPS-endpointiisi, allekirjoitettuina X-EC-Signature-otsakkeessa salaisuudella, joka on vain kyseiselle tilille.

t and s

Tiktok-Signature-otsakkeen kaksi osaa: toimituksen Unix-aikaleima sekunneissa ja TikTokin sille luoma allekirjoitus.

5 seconds

TikTokin Node-esimerkin acceptableDelay, joka hylkää oikein allekirjoitetun toimituksen, jos se on sitä vanhempi.

x-tt-logid

Otsake, joka kantaa jokaisen toimituksen yksilöllistä tunnistetta, jonka TikTok pyytää vastaanottajia kirjaamaan vianmääritystä varten.

BRAND_MENTION

Mainintawebhookien tapahtumatyyppi, jonka tilausopas viittaa samaan allekirjoituksen vahvistukseen.

v1

easyCoexistencen X-EC-Signature-otsakkeen allekirjoitusosa, HMAC-SHA256 t:stä, pisteestä ja raakarungosta.

Miltä Tiktok-Signature-otsake näyttää?

Kaksi osaa, pilkulla erotettuina: t, toimituksen Unix-aikaleima sekunneissa, ja s, allekirjoitus, pituudeltaan 64 heksadesimaalimerkkiä. TikTokin sivuilla nimi kirjoitetaan TikTok-Signature, Tiktok-Signature ja tiktok-signature; HTTP-otsakenimet eivät erota kirjainkokoa, joten lue se kirjainkoosta riippumatta, kuten useimmat kehykset jo tekevät. Muut otsakkeet TikTokin esimerkkitoimituksessa:

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

Mitä tavuja TikTok allekirjoittaa?

Arvon t merkkijonona, piste ja sitten runko. TikTokin opas kutsuu viimeistä osaa pyynnön rungon merkkijonoistetuksi JSON-kopioksi, ja sen Node-esimerkki rakentaa kopion suorittamalla JSON.stringify jo jäsennetylle oliolle. Tämä tuottaa TikTokin tavut vain niin kauan kuin molemmat sarjoittajat ovat samaa mieltä välilyönneistä, avainten järjestyksestä ja escapeamisesta, joten tiivistä runko täsmälleen sellaisena kuin se saapui, ennen kuin mikään JSON-välikerros lukee sen.

Mikä salaisuus on avain?

Kehittäjäsovelluksen salaisuus, joka löytyy TikTokin kehittäjäportaalista kohdasta My Apps, App Detail, Basic Information. Se on arvo, jonka sovellus jo lähettää kentässä secret kutsuihin /business/webhook/update/ ja kentässä client_secret tokenin päätepisteisiin. Yksi salaisuus allekirjoittaa toimitukset jokaiselle tilille, joka on valtuuttanut sovelluksen, joten vastaanottaja ei tarvitse avainta tilikohtaisesti, eikä käyttöoikeustunnus tai sovelluksen ID osallistu siihen.

Miten tarkistat sen Node.js-ympäristössä?

node:crypto-moduulilla ja raakarungolla. Alla oleva funktio jakaa otsakkeen, laskee HMAC:n uudelleen arvosta t, pisteestä ja rungon tavuista, vertaa tulosta vakioaikaisesti ja tarkistaa sitten t:n iän. Se ottaa allekirjoitusosan nimen argumenttina, joten sama koodi tarkistaa myös easyCoexistencen välitykset, joissa tuo osa on nimeltään v1 ja avain on tilin allekirjoitussalaisuus:

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
});

Kuinka vanha toimitus saa olla ennen kuin hylkäät sen?

TikTok jättää katkaisurajan vastaanottajalle: laske ero kellosi ja t:n välillä, sanoo sen opas, ja päätä, onko se sietämätön. Sen Node-esimerkki sallii 5 sekuntia, niin tiukka, että muutaman sekunnin verran väärässä oleva palvelinkello voisi hylätä aitoja toimituksia; yllä oleva koodi sallii 300, ikkunan jonka easyCoexistence pyytää vastaanottajia käyttämään omissa välityksissään. Mittaa t:stä, toimitusajasta jonka allekirjoitus kattaa, älä create_time-kentästä rungossa, joka merkitsee tapahtuman tapahtumishetken. TikTokin esimerkissä t on yhden sekunnin create_time-arvon jälkeen.

Mitä endpointin pitäisi vastata?

200 heti, kun allekirjoitus täsmää, ja työ tehdään sen jälkeen, koska TikTok pitää muuta tilaa epäonnistuneena toimituksena ja lähettää sen uudelleen. Väärästä allekirjoituksesta TikTokin esimerkki vastaa 4xx-tilalla ja kirjaa x-tt-logid-otsakkeen, joka tunnistaa pyynnön, jos ilmoitat ongelmasta TikTokille. client_key rungossa nimeää kehittäjäsovelluksen, joten sen vertaaminen omaan sovellus-ID:hen on halpa toinen tarkistus.

Miten callback-URL rekisteröidään, ja onko se vahvistettu?

Yhdellä API-kutsulla, eikä TikTok dokumentoi haastepyyntöä, joka testaisi URL:n ensin. POST /business/webhook/update/ ottaa app_id:n, secret-kentän, event_type:n ja HTTPS-osoitteen callback_url:n: VIDEO julkaisutapahtumille, COMMENT comment.update-tapahtumille ja Mentions API:ssa BRAND_MENTION brand.mention.event-tapahtumalle. Kaikki kolme saapuvat allekirjoitettuina samalla tavalla, ja GET /business/webhook/list/ näyttää tapahtumatyypille rekisteröidyn URL:n. Alkuperän todiste on jokaisen toimituksen allekirjoitus.

Voitko tarkistaa Tiktok-Signature-otsakkeen easyCoexistencen välittämissä tapahtumissa?

Ei, eikä siihen ole tarvetta. TikTok allekirjoittaa nuo toimitukset easyCoexistencen oman kehittäjäsovelluksen salaisuudella, jota mikään työkalu tai API ei luovuta. easyCoexistence tarkistaa allekirjoituksen jokaisen tapahtuman saapuessa, vastaa 401 epäonnistuneeseen, jättää huomiotta rungon, jonka client_key nimeää toisen sovelluksen, ja allekirjoittaa sitten välityksen sinulle X-EC-Signature-otsakkeessa yhdistetyn tilin allekirjoitussalaisuudella.

Miten easyCoexistence allekirjoittaa välittämänsä?

X-EC-Signature-otsakkeessa muodossa t=<unix>,v1=<hex>, missä t on välityksen aika ja v1 HMAC-SHA256 heksana t:stä, pisteestä ja rungosta täsmälleen lähetettynä. Avain on tilin allekirjoitussalaisuus, whsec_ ja sitä seuraavat 32 merkkiä, käytettynä kokonaisena etuliite mukaan lukien. Omista otsakkeistaan easyCoexistence asettaa vain Content-Type-otsakkeen ja tämän, ilman tapahtumaotsaketta, joten lue tapahtuman nimi kentästä entry.event:

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))

Mitä tapahtuu, kun allekirjoitussalaisuus vaihdetaan?

Uusi salaisuus allekirjoittaa seuraavasta välityksestä alkaen. Kutsu set_social_webhook_destination tai PUT /channels/{id}/webhook uudelleen palauttaa tuoreen salaisuuden ja poistaa vanhan heti, ja jokainen välitys lähetetään vain kerran, joten palvelimesi hylkäämä tapahtuma vaihdon aikana menetetään. Hyväksy molemmat salaisuudet muutaman minuutin ajan, kun uusi käyttöönotetaan. Kanavien ja julkaisujen tilatapahtumissa käytetään toista salaisuutta, sitä joka on Dashboard, Profile, Developers, ja ne saapuvat X-EC-Event- ja X-EC-Delivery-otsakkeilla, ja niitä yritetään uudelleen noin 33 tunnin ajan.

Yleiset virheet

  • Rungon vahvistaminen, jonka kehys on jo jäsentänyt. JSON-välikerros antaa olion, ja sen sarjoittaminen uudelleen voi muuttaa TikTokin tavuja; lue raakarunko webhook-reitillä.
  • 200:n vastaaminen toimitukselle, jonka allekirjoitus epäonnistui. TikTok lopettaa tapahtuman lähettämisen heti, kun se näkee 200:n, joten aito tapahtuma, jonka virheellisesti asetettu tarkistus hylkää, menetetään; 4xx saa TikTokin yrittämään uudelleen jopa 72 tuntia.
  • Allekirjoitusten vertaaminen ===-operaattorilla, kuten TikTokin esimerkki tekee. Vakioaikainen vertailu, kuten timingSafeEqual, ei paljasta, kuinka suuri osa väärennetystä allekirjoituksesta täsmäsi.
  • easyCoexistencen salaisuuden base64-dekoodaus tai sen whsec_-etuliitteen leikkaaminen pois. HMAC-avain on koko merkkijono täsmälleen sellaisena kuin se näytettiin kerran.
Näin teet tämän EasyCoexistencen avulla

Aseta endpoint set_social_webhook_destination-työkalulla Claudesta tai ChatGPT:stä, tai PUT /channels/{id}/webhook -kutsulla. US$ 9:stä US$ 0,75:een yhteyttä kohden kuukaudessa, ja hinta laskee yhteyksien määrän kasvaessa. Ensimmäiset 3 päivää ilmaiseksi.

Usein kysytyt kysymykset

Mikä on x-tt-logid TikTok-webhookissa?

Otsake, joka kantaa jokaisen toimituksen yksilöllistä tunnistetta. TikTok pyytää vastaanottajia kirjaamaan sen, koska se tunnistaa pyynnön, kun ilmoitat ongelmasta TikTokille.

Lähettääkö TikTok haasteen uuden webhook-URL:n vahvistamiseksi?

TikTok ei dokumentoi sellaista API for Business -rajapinnassaan. Kutsu /business/webhook/update/ rekisteröi URL:n, ja toimitukset saapuvat sen jälkeen Tiktok-Signature-otsakkeella, jonka palvelimesi tarkistaa.

Miksi TikTok-webhookini allekirjoitus ei koskaan täsmää?

Tarkista syöte ja avain: HMAC:n on katettava t, piste ja raakarunko sellaisena kuin se saapui, avaimena sovelluksen salaisuus, ja se on verrattava arvoon s= jälkeen, ei koko otsakkeeseen.

Miten vahvistan easyCoexistencen välittämät TikTok-tapahtumat?

X-EC-Signature-otsakkeella ja sillä allekirjoitussalaisuudella, joka näytettiin kohdetta asettaessasi: laske HMAC-SHA256 t:stä, pisteestä ja raakarungosta, vertaa sitä v1-arvoon ja hylkää t, joka on yli 5 minuuttia vanha.

Lue lisää

Yhdistä ensimmäinen kanavasi kahdessa minuutissa.

Ei alustojen tarkastuksia odotettavana. Yhdistä WhatsApp, Instagram, TikTok tai jokin muu kanava, pyydä sitten tekoälyäsi julkaisemaan, vastaamaan tai raportoimaan ja seuraa, kun se hoitaa homman.

  • 3 päivää ilmaiseksi
  • Peruuta milloin tahansa
  • Vain viralliset API:t
  • Valvottu 24/7

Vahvistettu