Server SDKs

Verify events, webhooks and sealed results in Node.js, Python, PHP and Java.

Every server SDK does the same three things: verify an event by id, verify a webhook signature, and open a sealed result. They are tested against the same vectors, produced by the server's own code, so they behave identically.

LanguagePackageInstall
Node.js 18.17+@trace-id/sdk-nodenpm install @trace-id/sdk-node
Python 3.9+trace-device (import trace_device)pip install trace-device
PHP 8.1+trace/tracecomposer require trace/trace
Java 11+dev.trace:traceMaven or Gradle
Ruby 3.0+trace-device (require trace)gem install trace-device
.NET 8TraceDevicedotnet add package TraceDevice
Go 1.21+github.com/trace-id/trace/sdks/go (package trace)go get github.com/trace-id/trace/sdks/go
Anything elseRESTGET /v1/events/:eventId with Authorization: Bearer sk_...

Verify an event

Fetches the event the browser created. Use it for every decision.

import { verifyEvent } from '@trace-id/sdk-node';

const event = await verifyEvent(eventId, { secretKey: 'sk_...', endpoint: 'https://id.example.com', timeoutMs: 2000 });
OptionDefaultDescription
secret keyrequiredsk_.... Keep it on the server.
endpointrequiredYour Trace server URL.
timeout2 sKeep it short; decide whether to fail open or closed.

The result is the event described in the API reference. Events can be verified for 60 minutes after they are created.

Verify errors

Node VerifyError (from @trace-id/sdk-node/errors), Python trace_device.VerifyError, PHP Trace\VerifyError ($errorCode), Java Trace.VerifyException Go *trace.VerifyError (Code), Ruby Trace::VerifyError (code) and .NET VerifyException (Code) all carry one of these codes:

CodeMeaning
invalid_event_idNot an event id.
unauthorizedMissing, wrong or revoked secret key.
not_foundNo such event in this project.
expiredOlder than the 60-minute verification window.
rate_limitedToo many requests.
timeout, networkThe server could not be reached in time.
server_error, invalid_responseThe server failed or answered unexpectedly.

Verify a webhook

Checks the X-Signature header against the endpoint's whsec_... secret and returns the parsed payload. Pass the raw request body; re-serialized JSON will not verify. Timestamps older than 300 seconds are rejected.

import { verifyWebhook } from '@trace-id/sdk-node/webhooks';

const payload = verifyWebhook({ body: rawBody, signature: req.headers['x-signature'], secret: 'whsec_...' });

Deliveries are at least once: dedupe on payload.id. Payload types are event.created and visitor.flagged. See receiving webhooks.

Open a sealed result

When the server has SEALED_RESULTS_KEY, the browser result includes sealedResult: the full event, encrypted. Your server opens it with the same key, without an API call. Pass several keys during a rotation.

import { unsealEventResult } from '@trace-id/sdk-node/sealed';

const event = unsealEventResult(body.sealedResult, { key: process.env.TRACE_SEALED_KEY! });

By default, results past the verification window are rejected (expired). Other errors: invalid_key, malformed, unsupported_version, tampered.

Embedded mode

With @trace-id/embed there is no HTTP call: await trace.verify(eventId) reads the event in process and throws a TraceError with status 404 or 410.

Suggest an edit

Spotted something wrong or unclear? Tell us on GitHub and we will fix it.