Gareth Wilson Gareth Wilson

Guide to Sahha Webhooks: Features and Best Practices

Published


Sahha turns data from phones and wearables into health scores, biomarkers and behavioural archetypes for each user of your app. Instead of polling its API for new results, you can have Sahha push them to your server as they're calculated, whether that's last night's sleep score, today's step count or a new chronotype.

Here we look at Sahha's five event types and their payloads, the header-based routing, X-Signature verification, and how the delivery interval changes what you receive.

What are Sahha webhooks?

Sahha webhooks are configured in the Sahha Dashboard. You give an HTTPS endpoint, pick the event types, copy a secret key and choose a delivery interval. Every request names the event type and your user's external ID in headers, and the body holds one record: a score, biomarker, archetype, tag or batch of raw data logs.

The interval controls how often scores and biomarkers arrive. With an interval set, Sahha holds later updates for the same metric and profile until the interval ends, then sends only the final value. Tags and data logs ignore the interval and always arrive immediately, since each carries new data rather than a revised value.

Sahha webhook features

FeatureDetails
Signaturehex HMAC-SHA256
Signature headerx-signature
BodyJSON
Event routingHeader field X-Event-Type

From Sahha's webhooks page:

  • Headers: X-Signature (the HMAC), X-External-Id (your identifier for the user) and X-Event-Type.
  • Delivery interval: real-time, or anywhere from 1 to 720 minutes, for scores and biomarkers.
  • A Send Test Event button in the dashboard.
  • Sahha waits up to 30 seconds for a 2xx.
  • Failed deliveries are retried up to 5 times with exponential backoff.
  • Events may arrive out of order, and Sahha says to use timestamps for sequencing.

Events and payloads

The event type is in the X-Event-Type header, not the body, so read it before parsing.

| Event routing | Header field X-Event-Type |

Event Payload Structure

  • Score: id, type, state, score (0.0-1.0), factors[], dataSources[], scoreDateTime, createdAtUtc, version
  • Biomarker: id, category, type, periodicity, aggregation, value (string), unit, valueType, startDateTime, endDateTime
  • Archetype: id, name, value, dataType, periodicity, ordinality, startDateTime, endDateTime
  • Tag: id, type (event or state), category, name, value, source, startDateTime, endDateTime, receivedAtUtc, additionalProperties
  • Data log: logType, dataType, receivedAtUtc, dataLogs[] (id, value, unit, source, startDateTime, endDateTime, ...)

Webhook bodies also carry profileId, accountId and externalId, and Sahha notes these metadata fields may not appear in its API responses. This ScoreCreatedIntegrationEvent example is from Sahha's event reference:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "profileId": "c9bf9e57-1685-4c89-bafb-ff5af830be8a",
  "accountId": "a3c1e8d2-4f6b-4a9c-8e7d-2b5f1c3a9e6b",
  "externalId": "user_12345",
  "type": "sleep",
  "state": "high",
  "score": 0.85,
  "factors": [
    {
      "id": "sleep_duration",
      "name": "sleep_duration",
      "value": 7.5,
      "goal": 8.0,
      "score": 0.94,
      "state": "high",
      "unit": "hour"
    }
  ],
  "dataSources": ["age", "sleep"],
  "scoreDateTime": "2025-01-22T00:00:00+00:00",
  "createdAtUtc": "2025-01-22T06:30:00Z",
  "version": 1.1
}

score, state and factor values can be null. Biomarker value is a string, with valueType telling you how to convert it.

Setting up Sahha webhooks

  1. In the Sahha Dashboard, open Webhooks in the sidebar.
  2. Add your HTTPS endpoint, for example https://example.com/webhooks/sahha.
  3. Select the event types.
  4. Copy the secret key and store it as SAHHA_WEBHOOK_SECRET.
  5. Set the interval for scores and biomarkers.
  6. Click Send Test Event to check your handler.

To route through Hookdeck, create a Sahha source with the secret key and register its URL as the endpoint. For local development:

npx hookdeck-cli listen 3000 sahha --path /webhooks/sahha

Securing Sahha webhooks

X-Signature is the hex HMAC-SHA256 of the raw request body, keyed with the secret key. The header holds the bare digest. Sahha's samples compare it case-insensitively, and nothing time-based is signed.

Node.js verification

const crypto = require('node:crypto');

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['x-signature'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const message = rawBody;
  const candidates = [signature];
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

The handler routes on the header, links the event to your user with X-External-Id, and stores the record before replying.

const express = require('express');

const app = express();

app.post('/webhooks/sahha', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.SAHHA_WEBHOOK_SECRET;
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  const eventType = req.get('x-event-type');
  const externalId = req.get('x-external-id');
  let record;
  try {
    record = JSON.parse(req.body.toString('utf8'));
  } catch {
    return res.sendStatus(400);
  }
  if (!record || typeof record !== 'object' || Array.isArray(record)) return res.sendStatus(400);

  try {
    switch (eventType) {
      case 'ScoreCreatedIntegrationEvent':
        await scores.upsert(externalId, record.type, record.scoreDateTime, record);
        break;
      case 'BiomarkerCreatedIntegrationEvent':
        await biomarkers.upsert(externalId, record.type, record.startDateTime, record);
        break;
      default:
        await rawEvents.insert(eventType, externalId, record);
    }
  } catch {
    return res.sendStatus(503);
  }

  res.sendStatus(200);
});

Upserting scores by type and date means a later update for the same day replaces the earlier one, which suits both the interval behaviour and out-of-order delivery.

Hookdeck's Sahha source checks the same HMAC, answers 200 and records mismatches as failed verification. Sahha signs no timestamp, so Hookdeck applies no time window.

Make Sahha webhooks production-ready. Hookdeck Event Gateway buffers bursts of real-time data logs and tags, and retries delivery to your service well beyond Sahha's five attempts.

Sahha webhook limitations and pain points

The event type is only in a header

The Problem: A stored body on its own doesn't say what kind of event it was.

Why It Happens: Sahha sends the type in X-Event-Type, and the body schemas don't include it.

Workarounds:

  • Store the header value alongside the body.
  • Keep separate tables per event type.

How Hookdeck Can Help: Hookdeck keeps headers with every request, and its filters can route on X-Event-Type to separate destinations.

Events can arrive out of order

The Problem: An older score can overwrite a newer one.

Why It Happens: Sahha doesn't guarantee ordering and retries failures with backoff.

Workarounds:

  • Compare createdAtUtc or receivedAtUtc with what you've stored before overwriting.
  • Upsert by profile, type and period, not by arrival.

How Hookdeck Can Help: Hookdeck's log shows when each event arrived, which helps you trace ordering issues.

Real-time intervals mean high volume

The Problem: With real-time delivery, every score and biomarker update is a request, on top of data logs and tags that are always immediate.

Why It Happens: Scores and biomarkers update throughout the day as data arrives, and only an interval batches them.

Workarounds:

  • Use the longest interval your product can tolerate.
  • Only subscribe to data logs if you need raw samples.

How Hookdeck Can Help: Hookdeck absorbs spikes and can rate-limit delivery to your service.

Five retries, then nothing

The Problem: A long outage loses health data.

Why It Happens: Sahha retries a failed delivery up to five times. The total time span isn't documented.

Workarounds:

  • Backfill from the Sahha API after downtime.
  • Alert on your endpoint's error rate.

How Hookdeck Can Help: Hookdeck accepts each delivery and keeps retrying your service under a policy you control.

Best practices

Map users with X-External-Id

Set the external ID when you create Sahha profiles, so each event maps straight to your user without a lookup on profileId.

Treat payloads as health data

Scores, biomarkers, tags (which can include symptoms and medication) and raw logs are sensitive. Keep them out of general logs and restrict who can read stored events.

Store, then process

Sahha's own handler samples process asynchronously. Store and return 2xx, then run analytics in a worker. Read why async webhook processing matters.

Dedupe on id

Retries resend the same record. Use the body id as a unique key, as covered in our webhook idempotency guide.

Conclusion

Sahha webhooks push health scores, biomarkers, archetypes, tags and raw data logs, with the event type in X-Event-Type and a hex HMAC-SHA256 in X-Signature. Choose the interval deliberately, upsert by period to cope with out-of-order delivery, and handle the data as sensitive health information.

Hookdeck Event Gateway verifies Sahha requests, routes them by event type and smooths out bursts.

Get started with Hookdeck for free and handle Sahha webhooks reliably in minutes.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.