This quickstart verifies Trace events in a Fastify app with the traceHook pre-handler from @trace-id/sdk-node.
Before you start
You need a secret key (sk_...) from the dashboard's Keys page and a frontend that sends an eventId (see the Web quickstarts). Send it in the x-trace-event-id header or as eventId in the request body.
- 1
Install the SDK
npm install @trace-id/sdk-nodepnpm add @trace-id/sdk-nodeyarn add @trace-id/sdk-node.envTRACE_SECRET_KEY=sk_... TRACE_ENDPOINT=https://id.example.com - 2
Guard a route
The hook reads the event id from the
x-trace-event-idheader or the parsed body, verifies it, and setsrequest.traceto the server-verified event.TypeScriptimport Fastify from 'fastify'; import { traceHook } from '@trace-id/sdk-node/fastify'; const app = Fastify(); app.post( '/api/signup', { preHandler: traceHook({ failOpen: true, reject: (event) => event.suspectScore >= 60 }) }, async (request) => { const event = request.trace; // null only with failOpen when Trace was unreachable // create the account, and store event?.visitorId with it for later lookups return { ok: true }; }, );The guard answers 400 for a missing or invalid event, 403 when
rejectsays so, 503 when Trace cannot be reached and 500 for a bad key or missing configuration.failOpen: truelets requests through (with the eventnull) when Trace is unreachable. A wrong key never fails open.To guard every route in a plugin, register it as a hook:
app.addHook('preHandler', traceHook()). For TypeScript, declare the property:TypeScriptimport type { EventResponse } from '@trace-id/signals/api'; declare module 'fastify' { interface FastifyRequest { trace?: EventResponse | null; } }Running Trace's own engine inside Fastify? See embedded mode.
Start in shadow mode
For the first week, log
event.suspectScoreandevent.reasonsinstead of rejecting. Look at who would have been blocked, then pick thresholds you trust.