Gareth Wilson Gareth Wilson

Guide to Hexclave Webhooks: Features and Best Practices

Published


Hexclave, previously called Stack Auth, is an open-source authentication and user-management platform. It stores your users and teams and handles sign-in for your app. Most products still keep their own user table alongside it, for billing, permissions or analytics, and Hexclave's webhooks are how that table stays current: a user signs up, changes their profile or is deleted, a team is created, someone joins or leaves a team, or a team permission is granted or removed.

The guide below lists Hexclave's 10 event types, shows where endpoints and secrets live, explains verifying the Svix signature, and points out what Hexclave's short webhook page leaves out.

What are Hexclave webhooks?

You create webhook endpoints in the Webhooks section of a Hexclave project's dashboard. Each one receives JSON POST requests of the form { "type": ..., "data": ... }, where data is the user, team, membership or permission that changed. Hexclave's docs still say "Stack" in places, from before the rename.

Delivery runs on Svix. Hexclave's example handlers read the svix-id, svix-timestamp and svix-signature headers and pass them to the Svix library, and Hexclave links Svix's own documentation for verifying in other languages.

Hexclave webhook features

FeatureDetails
ConfigurationProject dashboard, Webhooks section
Delivery platformSvix
Headerssvix-id, svix-timestamp, svix-signature
SignatureStandard Webhooks HMAC-SHA256, v1,<base64>
SecretPer endpoint, in its details (Svix secrets start with whsec_)
Body{type, data}
Event routingBody field type
Retries, timeout, orderingNot documented
Source IPsNot published

Events and payloads

Documented eventMeaning
user.createdThis event is triggered when a user is created.
user.updatedThis event is triggered when a user is updated.
user.deletedThis event is triggered when a user is deleted.
team.createdThis event is triggered when a team is created.
team.updatedThis event is triggered when a team is updated.
team.deletedThis event is triggered when a team is deleted.
team_membership.createdThis event is triggered when a user is added to a team.
team_membership.deletedThis event is triggered when a user is removed from a team.
team_permission.createdThis event is triggered when a team permission is created.
team_permission.deletedThis event is triggered when a team permission is deleted.

The overview page shows a team.created delivery with data cut short, roughly:

{
  "type": "team.created",
  "data": {
    "id": "2209422a-eef7-4668-967d-be79409972c5",
    "display_name": "My Team",
    ...
  }
}

Hexclave's API reference has a schema for each event's data, but no full example bodies. Read the fields you need from the schema and confirm them against a real delivery.

Setting up Hexclave webhooks

  1. Open your project in the Hexclave dashboard and go to Webhooks.
  2. Create an endpoint with your HTTPS URL, for example https://example.com/webhooks/hexclave.
  3. Open the endpoint's details and copy its signing secret into HEXCLAVE_WEBHOOK_SECRET.

Hexclave's page doesn't show the secret's format. Svix secrets start with whsec_, and both the code below and Hookdeck's Hexclave source expect that form, so check it when you copy it. To try deliveries locally, start the Hookdeck CLI and create the endpoint with the URL it prints:

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

With Hookdeck. Set up a Hookdeck source with the Hexclave type, paste the endpoint's secret, and make the source URL the endpoint in Hexclave. Only POST is accepted. Hookdeck sends Hexclave a 200 in all cases; where the signature doesn't verify, the request is flagged as failed verification and not delivered to your app.

Securing Hexclave webhooks

Hexclave asks you to verify every request so that a forged or replayed request can't change your user data. With Svix's scheme, the signed content is {svix-id}.{svix-timestamp}.{raw body}, the key is the base64-decoded secret after whsec_, and svix-signature lists one or more v1,<base64> values separated by spaces. The verifier below accepts any matching v1 value and falls back to webhook-* header names:

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

function decodeBase64(value) {
  if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
  const bytes = Buffer.from(value, 'base64');
  return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
    ? bytes : null;
}

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const prefix = headers['svix-id'] ? 'svix' : 'webhook';
  const id = headers[`${prefix}-id`];
  const timestamp = headers[`${prefix}-timestamp`];
  const signature = headers[`${prefix}-signature`];
  if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
      !/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
  const key = decodeBase64(secret.replace(/^whsec_/, ''));
  if (!key) return false;
  const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
  const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    const received = decodeBase64(candidate);
    if (!received) return false;
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

A handler that mirrors users and memberships into your own tables:

const express = require('express');

// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
  try {
    const value = JSON.parse(rawBody.toString('utf8'));
    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
  } catch {
    return null;
  }
}

const app = express();

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

  const payload = parseJsonObject(req.body);
  if (!payload) return res.sendStatus(400); // signed, but not a JSON object
  const { type, data } = payload;
  if (typeof type !== 'string' || !data || typeof data !== 'object') return res.sendStatus(400);
  try {
    switch (type) {
      case 'user.created':
      case 'user.updated':
        await db.users.upsert(data.id, data);
        break;
      case 'user.deleted':
        await db.users.remove(data.id);
        break;
      case 'team_membership.created':
      case 'team_membership.deleted':
        await syncQueue.add({ type, data }); // membership changes can affect billing seats
        break;
      default:
        break;
    }
  } catch {
    return res.sendStatus(503); // not processed, so don't acknowledge
  }
  return res.sendStatus(200);
});

db and syncQueue are placeholders for your own storage.

Hexclave's handlers use the Svix library, which rejects any request whose svix-timestamp is more than 5 minutes from your clock. That's a problem if Hookdeck sits in front of you: Hookdeck sets no age limit and resends Hexclave's original timestamp on retry or replay. The function above doesn't check age; idempotent upserts and deletes protect you from replays instead.

Make Hexclave webhooks production-ready. Hookdeck Event Gateway verifies Hexclave's Svix signatures and stores every user and team change, so your own database can catch up after downtime.

Hexclave webhook limitations and pain points

Delivery behaviour isn't documented

The Problem: You don't know how long Hexclave keeps retrying a user event your server missed.

Why It Happens: Hexclave's webhook page covers setup and verification only. It gives no retry schedule, timeout or disabling rule. Svix's defaults probably apply, but Hexclave doesn't confirm it.

Workarounds:

  • Respond quickly and do database work afterwards.
  • Periodically reconcile your user table against Hexclave's API.

How Hookdeck Can Help: Hookdeck accepts events as they arrive and retries delivery into your app on your terms.

Events can arrive out of order

The Problem: A user.updated lands after user.deleted and recreates a user you removed.

Why It Happens: Hexclave makes no ordering promise, and retries can reorder deliveries.

Workarounds:

  • Keep a tombstone for deleted users and ignore later updates for them.
  • When in doubt, fetch the user from Hexclave's API and write what it returns.

How Hookdeck Can Help: Hookdeck's event log shows the arrival order of each user's events when you need to untangle a sync problem.

Thin documentation of payloads

The Problem: You're coding against data without a full example.

Why It Happens: The only example elides data, and the API reference gives schemas without bodies.

Workarounds:

  • Capture a real event for each type in a development project before relying on optional fields.

How Hookdeck Can Help: Hookdeck keeps every request a source receives, headers and body, so captured events double as fixtures you can replay.

The secret format isn't stated

The Problem: A verifier or gateway that expects whsec_ silently uses the wrong key.

Why It Happens: Hexclave doesn't show the secret on its docs page; the whsec_ form comes from Svix.

Workarounds:

  • Check the prefix when you copy the secret, and fail closed at startup if it's missing.

How Hookdeck Can Help: When a secret is wrong, failed verifications show up in Hookdeck straight away rather than as unexplained gaps in your data.

Best practices

Keep the body raw

Hexclave's examples verify the raw text body. Read bytes with express.raw({ type: '*/*' }), await request.text() in a Next.js route handler, or await request.body() in FastAPI, and only parse after the check passes.

Make writes idempotent

Upserts by data.id and deletes that tolerate a missing row make duplicate deliveries harmless. Svix keeps svix-id the same across resends, so you can also store it. Our webhook idempotency guide has patterns.

Handle new types gracefully

Return 200 for event types you don't handle. Hexclave doesn't describe its list of 10 as final, and an unknown type shouldn't count as a failed delivery.

Conclusion

Hexclave's webhooks keep your copy of users, teams and permissions in step with the auth system, using a standard Svix signature. Confirm the secret is in whsec_ form, verify against the raw body, make every write idempotent, and guard against updates that arrive after deletes, since Hexclave says nothing about ordering or retries.

Hookdeck Event Gateway adds the delivery guarantees Hexclave's docs don't spell out: every event stored, retried into your app and available to replay. Get started free with a Hexclave source.


Gareth Wilson

Gareth Wilson

Product Marketing

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