# Sahha Webhooks

[Sahha](https://sahha.ai) is a health-data API that turns wearable and phone data into scores, biomarkers and archetypes per user profile. Its webhooks push those results, tags and raw data logs to your server. Each delivery is a `POST` signed with an `X-Signature` header.

## When to Use This Skill

* How do I receive Sahha webhooks?
* How do I verify a Sahha webhook signature (`X-Signature`)?
* Where do I find my Sahha webhook secret key?
* How do I handle `ScoreCreatedIntegrationEvent` or `BiomarkerCreatedIntegrationEvent`?
* Why is my Sahha webhook signature verification failing?

## Verification (core)

| Header | Value |
| --- | --- |
| `X-Signature` | Bare hex HMAC-SHA256 of the **raw request body**, no prefix |
| `X-Event-Type` | Event type, for example `ScoreCreatedIntegrationEvent` |
| `X-External-Id` | The profile's external identifier |

The key is the Dashboard secret as UTF-8 bytes (not decoded). Only the body is signed, so there is no timestamp or replay window. Sahha has no webhook SDK, so verify manually. Check the header is exactly 64 hex characters, decode to bytes (hex is case-insensitive) and compare in constant time:

```javascript
const crypto = require('crypto');

// rawBody: Buffer of the exact bytes received (express.raw({ type: '*/*' }))
function verifySahhaSignature(rawBody, signature, secret) {
  if (typeof signature !== 'string' || !/^[0-9a-fA-F]{64}$/.test(signature)) return false;
  const expected = crypto.createHmac('sha256', Buffer.from(secret, 'utf8')).update(rawBody).digest();
  const provided = Buffer.from(signature, 'hex'); // safe: format validated above
  return provided.length === expected.length && crypto.timingSafeEqual(provided, expected);
}

```

Python: `hmac.new(secret.encode(), raw_body, hashlib.sha256).digest()` compared with `hmac.compare_digest(bytes.fromhex(sig), expected)` after `re.fullmatch(r"[0-9a-fA-F]{64}", sig)`. Respond `401` for a missing, empty or malformed header and for a mismatch. Parse JSON only after the check.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/sahha-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/sahha-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/sahha-webhooks/examples/fastapi/).

## Common Event Types

Dispatch on the `X-Event-Type` header.

| Event | Fired when |
| --- | --- |
| `ScoreCreatedIntegrationEvent` | A health score (activity, sleep, readiness, wellbeing, ...) is generated or updated |
| `BiomarkerCreatedIntegrationEvent` | A biomarker value (steps, heart rate, sleep duration, ...) is calculated |
| `ArchetypeCreatedIntegrationEvent` | A profile is assigned an archetype (chronotype, activity level, ...) |
| `TagReceivedIntegrationEvent` | A tag (symptom, medication, shift, subscription, ...) is received |
| `DataLogReceivedIntegrationEvent` | Raw samples arrive from a user's device |

> **Full payloads:** [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/sahha-webhooks/references/overview.md) and [Sahha's event reference](https://sahha.ai/docs/connect/webhooks/events/).

## Delivery Semantics

* Return a `2xx` within **30 seconds**; enqueue heavy work.
* Failed deliveries are retried up to **5 times** with exponential backoff.
* Events can arrive out of order; sequence with payload timestamps.
* Scores and biomarkers are held for the configured interval (real-time to 720 minutes) and only the final value is sent. Data logs and tags are always immediate.
* Tags are identified by `profileId + name + type + source + startDateTime`, not `id`, and may be re-sent.

## Environment Variables

```bash
SAHHA_WEBHOOK_SECRET=your_sahha_webhook_secret_here   # Dashboard > Webhooks; handlers fail closed (500) without it

```

## Local Development

```bash
# Express / Next.js (use 8000 for FastAPI). No install or account required.
npx hookdeck-cli listen 3000 sahha --path /webhooks/sahha

```

Add the printed URL on the Dashboard **Webhooks** page and use **Send Test Event**.

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/sahha-webhooks/references/overview.md) - Event catalog, headers, payload fields, delivery behaviour
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/sahha-webhooks/references/setup.md) - Dashboard setup, secret key, interval, testing
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/sahha-webhooks/references/verification.md) - Verification details, gotchas, debugging