Integration guide

A practical, end-to-end walkthrough for getting Helix Security live in your product — from signing up to receiving signed webhooks in production.

Estimated time: ~20 minutes.

1. Create your workspace

1. Go to /signup and create an account with your work email.
2. Verify your email (check spam if you don't see it).
3. On first login you'll land in the Onboarding flow — pick a workspace name (this becomes your tenant) and the region your data should live in.

You're now the owner of a fresh tenant. Invite teammates later under Settings → Users.

2. Register an application

An application represents one product surface (e.g. ios-consumer-app, web-checkout). Each application owns its own SDK keys and webhook subscriptions, so revoking one never breaks another.

1. Open Applications in the sidebar.
2. Click New application.
3. Give it a slug (web-checkout) and a human label ("Web Checkout").

3. Mint an SDK key (hk_…)

1. From the application detail page, click Generate SDK key.

2. Copy the full key — it's shown once. It looks like:

    hk_a1b2c3d4e5f6_<random>
   

3. Store it in your secret manager. The key is hashed (SHA-256) at rest; we cannot recover it.

4. Revoke a key at any time from the same screen. Revoked keys return 401 immediately on the next request.

Use one key per environment (e.g. dev, staging, prod) so you can rotate independently.

4. Call the Events API

Send every risk-scoring event from your SDK to:

POST https://<your-domain>/api/public/v1/events
Authorization: Bearer hk_<your-sdk-key>
Content-Type:  application/json
Idempotency-Key: <uuid-per-attempt>      # recommended

Minimal example (Node / fetch)

const res = await fetch("https://api.helixsecure.co.uk/api/public/v1/events", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.HELIX_SDK_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    session_id: "sess_3f9a…",
    score: 72,
    signals: { device_tilt: 0.81, touch_pressure: 0.42 },
  }),
});

const { decision } = await res.json();
// "allow" | "review" | "block"

The response carries the inline decision computed against your active policy. Use it to gate the in-flight transaction:

See the interactive API reference for the full schema, error codes, and a "Try it" console.

5. Configure webhook destinations

Webhooks let your downstream systems (fraud-ops, payment switch, CRM, SIEM) react to every decision asynchronously.

1. Open Webhooks in the sidebar.
2. Click New webhook.
3. Enter the destination URL on your side (must be HTTPS).
4. Choose which event types to subscribe to:
   • risk_event.allow
   • risk_event.review
   • risk_event.block
   • * — everything
5. Save. Helix mints a signing secret and shows it once — copy it into your secret manager.

Verify signatures on your side

Every delivery carries an x-helix-signature: t=<unix>,v1=<hex> header. v1 is HMAC_SHA256(secret, "<t>.<raw-body>"). Reject anything older than 5 minutes and always compare with a timing-safe equality check. See Webhooks for a Node verifier you can copy verbatim.

Test before you ship

Each webhook has a Send test event button that POSTs a signed helix.test payload and records the round-trip status in the audit log. Use it to prove signature verification works before enabling real traffic.

6. Promote to production

• Switch your SDK to the production hk_ key.
• Add your production webhook destination and remove the staging one.
• Walk the deployment checklist.
• Subscribe to status emails under Settings → Notifications.

You're live. Open the Dashboard to watch events stream in.