Install the SDK and it will read your key from the environment automatically.

# npm, pnpm or bun
npm install @relay/sdk

# then, in your app
import { Relay } from "@relay/sdk";

Node 18 or newer is required for the built-in fetch client.

Use a scoped token in anything that runs outside your own infrastructure. Secret keys should never reach the browser.

const relay = new Relay({
  token: process.env.RELAY_SCOPED_TOKEN,
  scopes: ["events:read"]
});

Every write accepts an idempotency key. Retries with the same key return the original response instead of creating a duplicate.

await relay.events.send(payload, {
  idempotencyKey: order.id,
  retries: 4          // exponential backoff
});

Verify the signature before trusting a payload. The helper below also rejects anything older than five minutes.

const event = relay.webhooks.verify(
  rawBody,
  request.headers["relay-signature"],
  process.env.RELAY_WEBHOOK_SECRET
);

Always verify against the raw request body — parsed JSON will not match the signature.