# Guide to Hexclave Webhooks: Features and Best Practices

[Hexclave](https://hexclave.com), 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

| Feature | Details |
| --- | --- |
| Configuration | Project dashboard, **Webhooks** section |
| Delivery platform | Svix |
| Headers | `svix-id`, `svix-timestamp`, `svix-signature` |
| Signature | Standard Webhooks HMAC-SHA256, `v1,<base64>` |
| Secret | Per endpoint, in its details (Svix secrets start with `whsec_`) |
| Body | `{type, data}` |
| Event routing | Body field `type` |
| Retries, timeout, ordering | Not documented |
| Source IPs | Not published |

## Events and payloads

| Documented event | Meaning |
| --- | --- |
| `user.created` | This event is triggered when a user is created. |
| `user.updated` | This event is triggered when a user is updated. |
| `user.deleted` | This event is triggered when a user is deleted. |
| `team.created` | This event is triggered when a team is created. |
| `team.updated` | This event is triggered when a team is updated. |
| `team.deleted` | This event is triggered when a team is deleted. |
| `team_membership.created` | This event is triggered when a user is added to a team. |
| `team_membership.deleted` | This event is triggered when a user is removed from a team. |
| `team_permission.created` | This event is triggered when a team permission is created. |
| `team_permission.deleted` | This event is triggered when a team permission is deleted. |

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

```json
{
  "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](/docs/cli) and create the endpoint with the URL it prints:

```bash
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:

```javascript
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:

```javascript
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](/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](/docs/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](/webhooks/guides/implement-webhook-idempotency) 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](https://hookdeck.com) 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](https://dashboard.hookdeck.com/signup) with a Hexclave source.