Sahha x Convex Integration

Use the Sahha Demo App (fastest way to test)

1. In the Sahha dashboard, go to Configure → Demo App
2. Copy the Configuration URL (or scan the QR code)
3. Install the Sahha Demo App from the App Store / Google Play
4. In the demo app, paste the Configuration URL (or scan the QR) to connect it to your project
5. Keep the demo app running so it can collect and submit device data

Once connected, you should see a new profile appear in your Sahha project and data beginning to flow.

If you’ve already integrated the Sahha SDK into your application, ensure that:

• Your app is successfully streaming data to Sahha
• You are setting a stable externalId when creating Sahha profiles (for example, your Convex user ID)

This externalId will later be sent back in webhooks as X-External-Id, which allows you to map Sahha events to the correct user in your database.

Download the starter project — it includes an HTTP Action with signature verification, a schema definition, and all project configuration already set up.

After downloading:

1. Unzip and open the project
2. Install dependencies:

cd sahha-convex-webhooks-starter
npm install

3. Start the Convex dev server:

npx convex dev

Convex will deploy your schema and functions automatically.

Create a new project

mkdir sahha-convex-webhooks
cd sahha-convex-webhooks
npm init -y
npm install convex

Initialize Convex

npx convex dev

This creates a convex/ directory and links your project. Press Ctrl+C to stop the dev server for now — we’ll restart it after adding the files.

Create the schema

Create convex/schema.ts:

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  sahhaEvents: defineTable({
    eventType: v.string(),
    externalId: v.string(),
    payload: v.any(),
    eventHash: v.string(),
    receivedAt: v.number(),
  })
    .index("by_event_hash", ["eventHash"])
    .index("by_external_id", ["externalId"])
    .index("by_event_type", ["eventType"]),
});

Create the webhook mutation

Create convex/webhooks.ts:

import { internalMutation } from "./_generated/server";
import { v } from "convex/values";

export const store = internalMutation({
  args: {
    eventType: v.string(),
    externalId: v.string(),
    payload: v.any(),
    eventHash: v.string(),
  },
  handler: async (ctx, args) => {
    const existing = await ctx.db
      .query("sahhaEvents")
      .withIndex("by_event_hash", (q) => q.eq("eventHash", args.eventHash))
      .first();

    if (existing) {
      return;
    }

    await ctx.db.insert("sahhaEvents", {
      ...args,
      receivedAt: Date.now(),
    });
  },
});

Create the HTTP action

Create convex/http.ts:

import { httpRouter } from "convex/server";
import { httpAction } from "./_generated/server";
import { internal } from "./_generated/api";

const encoder = new TextEncoder();

async function hmacSha256(
  secret: string,
  data: Uint8Array,
): Promise<string> {
  const key = await crypto.subtle.importKey(
    "raw",
    encoder.encode(secret),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["sign"],
  );
  const sig = await crypto.subtle.sign("HMAC", key, data);
  return [...new Uint8Array(sig)]
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");
}

async function sha256Hex(data: Uint8Array): Promise<string> {
  const hash = await crypto.subtle.digest("SHA-256", data);
  return [...new Uint8Array(hash)]
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");
}

const http = httpRouter();

http.route({
  path: "/sahha-webhook",
  method: "POST",
  handler: httpAction(async (ctx, request) => {
    try {
      const signature = (request.headers.get("x-signature") ?? "").trim();
      const eventType = (request.headers.get("x-event-type") ?? "").trim();
      const externalId = (request.headers.get("x-external-id") ?? "").trim();

      if (!signature) {
        return new Response("Missing X-Signature", { status: 400 });
      }

      const secret = process.env.SAHHA_WEBHOOK_SECRET ?? "";
      if (!secret) {
        return new Response("Missing SAHHA_WEBHOOK_SECRET", { status: 500 });
      }

      const rawBody = new Uint8Array(await request.arrayBuffer());

      const computed = await hmacSha256(secret, rawBody);
      if (computed !== signature) {
        return new Response("Invalid signature", { status: 401 });
      }

      const payload = JSON.parse(new TextDecoder().decode(rawBody));
      const eventHash = await sha256Hex(rawBody);

      await ctx.runMutation(internal.webhooks.store, {
        eventType: eventType || "unknown",
        externalId,
        payload,
        eventHash,
      });

      return new Response("ok", { status: 200 });
    } catch (err) {
      console.error("Webhook error:", err);
      return new Response("Server error", { status: 500 });
    }
  }),
});

export default http;

Now restart the dev server to deploy everything:

npx convex dev