TikTok Events API node for n8n

TikTok Events APIsends TikTok conversion events from n8n. Map raw values and the node normalizes and SHA-256 hashes them to TikTok's own rules, omits absent fields rather than sending a hash of an empty string, and keeps your access token in a credential instead of the workflow. MIT licensed. Source, npm.

TikTok reference: Events API, report a web event

Setup

In n8n: Settings, Community nodes, Install, then enter the package name.

n8n-nodes-tiktok-events-api

Add a trigger, a Webhook is the common one, then add TikTok Events API. Webhook into the node is the whole workflow.

Pixel Code: from TikTok Events Manager.
Event Name, and Page URL for website events.
Map at least Email or Phone under Customer Information, plus Client IP Address and Client User Agent. TikTok: "When there's no pii information available, you can send us both ip and user_agent."
Set Options, Test Event Code while testing, then remove it to go live.

Credential

One token, and no choice to make: generate an access token in TikTok Events Manager under your pixel, or from the TikTok for Business developer portal if you already have an app there. The node sends it as an Access-Token header.

The credential holds the token and nothing else. Pixel Code is a node parameter, because one token often covers several pixels and a node-level value can be an expression.

n8n tests the token as soon as you save it. Green means the token is valid and unexpired: it does not check access to any particular pixel. TikTok answers an unauthenticated request with HTTP 403, so a bad token fails loudly, unlike a bad event.

Parameters

Parameter	What it is	Where to find it / accepted values
Pixel Code	The pixel the event is written to.	From TikTok Events Manager. Supports an expression, so one workflow can route to several pixels.
Event Name	The event TikTok records.	TikTok's 18 standard web events, or Custom Event to type your own. Custom events can be reported on and used for audiences, but TikTok cannot optimize for them.
Page URL	The page URL the event happened on.	Sent as the event's page URL.
Event ID	Deduplication key against the TikTok Pixel.	Required if you send the same event from both the Pixel and this node. Leave empty and the node generates one from the execution ID, which is idempotent on retry but will not deduplicate against the Pixel.
Event Time	When the event happened.	Unix seconds, Unix milliseconds, or an ISO date, sent to TikTok as Unix seconds. Leave empty for now.
Value	Monetary value of the conversion.	Empty sends no value. Required for Return on Ad Spend and Value-Based Optimization. Must be an integer or decimal, with no currency signs or commas.
Currency	ISO 4217 code for Value.	Only sent when Value is set. TikTok supports a fixed currency list.

Standard events

TikTok's 18 standard web events. Use the exact name: "Please make sure to use the exact name as shown in Event as it is case sensitive."

AddPaymentInfo   AddToCart   AddToWishlist   ApplicationApproval   CompleteRegistration   Contact   CustomizeProduct   Download   FindLocation   InitiateCheckout   Lead   Purchase   Schedule   Search   StartTrial   SubmitApplication   Subscribe   ViewContent

Lead is "Submit form"

Lead is the API name; Events Manager shows it as Submit form. The reporting name and the API name differ, which is a common source of "my event never arrived".

Customer information

Map raw values. Email, phone and external ID are normalized to TikTok's rules and SHA-256 hashed. Fields left empty are omitted, never sent as a hash of an empty string. Values that are already SHA-256 digests are passed through rather than hashed twice.

TikTok: "To increase the probability of matching website visitor events with TikTok ads and improve your ads performance, we recommend as much information as possible."

Field	Sent as	Normalization
Email	`email`, hashed	Lowercased, then hashed. Sent as an array.
Phone	`phone`, hashed	Keeps the leading + and the country code, separators removed. Country code 86 is dropped entirely. Sent as an array.
External ID	`external_id`, hashed	Your stable user ID, trimmed. Sent as a string, not an array.
Ttclid (Click ID)	`ttclid`, raw	TikTok's click ID from the landing page URL. The strongest signal available.
Ttp (Cookie ID)	`ttp`, raw	The _ttp cookie set by the TikTok Pixel.
Client IP Address	`ip`, raw	IPv4 or IPv6. An X-Forwarded-For chain is reduced to the client IP.
Client User Agent	`user_agent`, raw	Passed through.

The phone rule

TikTok is specific, and unusual, about phone numbers:

Prior to hashing, format the phone number: If the country code is 86, then do not include country code (example: 13800000000). Otherwise, include country code with + and remove any other characters (spaces, '-') between numbers (example for US: +12133734253)
TikTok, Report a Web Event

You map	TikTok hashes
`+1 (213) 373-4253`	`+12133734253`
`+86 138 0000 0000`	`13800000000`

The leading + is kept, which is the opposite of what several other platforms want, and the China carve-out inverts the rule entirely. Hash the wrong shape and you send a well-formed digest that matches nobody, while TikTok still answers code: 0. Map the raw number and let the node format it.

Numbers with no country code

A bare national number is dropped rather than guessed at, because guessing the country produces a hash that matches nobody. Set Default Country Calling Code and they get one.

Properties

Key and value pairs sent inside properties, such as content_id or content_type. Values are sent as-is. TikTok recommends content_type, contents, content_id, currency and value for Return on Ad Spend and Video Shopping Ads.

Options

Option	What it does
Test Event Code	Routes the event to Test Events instead of counting it. From TikTok Events Manager, under your pixel. The code is per-pixel.
Default Country Calling Code	Prepended to phone numbers that arrive without one, e.g. 1. A phone without a country code will not match.
Page Referrer	The HTTP referrer of the page that triggered the event.

Output

One item per event, carrying TikTok's response and the event as sent.

{
  "code": 0,
  "message": "OK",
  "request_id": "2019091810032301011023224213558",
  "event_source_id": "ABCDE12345FGHIJ67890",
  "test_event_code": "TEST12345",
  "event": {
    "event": "Contact",
    "event_time": 1784059038,
    "event_id": "12345",
    "user": {
      "email": ["06a418f467a14e1631a317b107548a10..."],
      "ip": "254.254.254.254",
      "user_agent": "Mozilla/5.0 ..."
    },
    "page": { "url": "https://example.com/thanks" }
  }
}

The event is returned exactly as it went out, hashed, so you can see what TikTok actually received. code: 0 means accepted. Anything else is a rejection, and the node fails the item rather than returning it as a success: TikTok answers HTTP 200 either way, so the status alone would report every failure as a delivered conversion.

Testing

TikTok Events Manager, your pixel, the Test Events tab. Copy the test event code.
On the node, under Options, add Test Event Code and paste it.
Execute. The event appears in Test Events within a few seconds, showing the event name, the connection method (Server) and the identifiers it received.
When it looks right, remove the code. While it is set, the event does not count as a real conversion.

code: 0 is not success

It means TikTok parsed the request. Not that the event was accepted, matched, attributed, or treated as a test. An event with no usable identifiers returns exactly the same response as one that worked.

The Test Events view shows which identifiers arrived, so a hashed email appearing there is proof the normalization reached TikTok intact. That, not the response, is what tells you it works. Watch the name while you are there: the node sends Lead and Events Manager lists it as Submit form.

Best practices covers what TikTok asks you to do beyond getting the request accepted.