oura-webhooks

Oura Webhooks

When to Use This Skill

• How do I receive Oura webhooks?
• How do I complete the Oura subscription verification handshake (GET challenge)?
• How do I verify the x-oura-signature header?
• Why is my Oura webhook signature verification failing?
• How do I handle Oura sleep, daily_readiness, or workout events?

How Oura Webhooks Work

Oura webhooks have two distinct request types on the same callback URL:

1. Subscription handshake (GET): When you create a subscription, Oura sends a GET to your callback_url with query params verification_token and challenge. Check the token matches yours, then respond 200 with JSON {"challenge": "<value>"}.
2. Event delivery (POST): Each event is a POST carrying headers x-oura-signature and x-oura-timestamp. Verify the HMAC, then process.

Event payloads are thin — { event_type, data_type, object_id, event_time, user_id }. Use object_id to fetch the full record from the Oura API.

Verification (core)

HMAC-SHA256 over timestamp + rawBody, keyed with your client secret, hex digest, UPPERCASE. Compare (timing-safe) to the x-oura-signature header. Use the raw request body — see references/verification.md for why raw body is used instead of re-serializing (JSON.stringify) the parsed payload.

Node:

const crypto = require('crypto');

function verifyOuraSignature(rawBody, signature, timestamp, clientSecret) {
  if (!signature || !timestamp) return false;
  const expected = crypto
    .createHmac('sha256', clientSecret)
    .update(timestamp + rawBody)          // x-oura-timestamp + raw request body
    .digest('hex')
    .toUpperCase();                        // Oura sends an uppercase hex digest
  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch {
    return false;                          // length mismatch = invalid
  }
}

Python:

import hmac, hashlib

def verify_oura_signature(raw_body: bytes, signature: str, timestamp: str, client_secret: str) -> bool:
    if not signature or not timestamp:
        return False
    expected = hmac.new(
        client_secret.encode("utf-8"),
        timestamp.encode("utf-8") + raw_body,   # x-oura-timestamp + raw request body
        hashlib.sha256,
    ).hexdigest().upper()
    return hmac.compare_digest(expected, signature)