Agent skill
Sahha Webhooks Skill
Receive and verify Sahha (sahha.ai) health-data webhooks. Use when setting up a Sahha webhook endpoint, getting the Dashboard secret key, debugging X-Signature HMAC-SHA256 verification, or handling ScoreCreatedIntegrationEvent, BiomarkerCreatedIntegrationEvent, ArchetypeCreatedIntegrationEvent, TagReceivedIntegrationEvent and DataLogReceivedIntegrationEvent events.
Install this skill
npx skills add hookdeck/webhook-skills --skill sahha-webhooks
Sahha 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
ScoreCreatedIntegrationEventorBiomarkerCreatedIntegrationEvent? - 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:
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_ compared with hmac.compare_ 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/, examples/nextjs/, 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 and Sahha's event reference.
Delivery Semantics
- Return a
2xxwithin 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, notid, and may be re-sent.
Environment Variables
SAHHA_WEBHOOK_SECRET=your_sahha_webhook_secret_here # Dashboard > Webhooks; handlers fail closed (500) without it
Local Development
# 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 - Event catalog, headers, payload fields, delivery behaviour
- references/setup.md - Dashboard setup, secret key, interval, testing
- references/verification.md - Verification details, gotchas, debugging