Agent skill

Hexclave Webhooks Skill

Receive and verify Hexclave (formerly Stack Auth) webhooks, which are delivered by Svix. Use when setting up a Hexclave webhook endpoint, getting the whsec_ endpoint secret, debugging svix-id / svix-timestamp / svix-signature verification, or handling user and team events like user.created, user.updated, team.created and team_membership.created.

Install this skill

npx skills add hookdeck/webhook-skills --skill hexclave-webhooks


Hexclave (formerly Stack Auth) is an open-source auth and user-management platform. It POSTs a signed JSON event to your endpoint when a user, team, team membership or team permission is created, updated or deleted. Deliveries are sent through Svix, so they carry svix-id, svix-timestamp and svix-signature headers. Hexclave's docs still say "Stack" in places.

When to Use This Skill

  • How do I receive Hexclave (Stack Auth) webhooks?
  • How do I verify a Hexclave webhook signature (svix-signature)?
  • Where do I find my Hexclave webhook secret (whsec_...)?
  • How do I handle user.created, user.updated, team.created or team_membership.created events?
  • Why is my Hexclave webhook verification failing?

Verification (core)

HeaderValue
svix-idIdentifies the message; retries reuse it
svix-timestampUnix seconds
svix-signatureOne or more space-separated v1,<base64> entries

Signed content is {svix-id}.{svix-timestamp}.{raw body}, HMAC-SHA256, base64 output. The key is the base64-decoded part of the whsec_... secret after the prefix. Compare against every v1, entry; ignore other versions. If svix-id is absent, read webhook-id, webhook-timestamp and webhook-signature instead. The examples use the svix library (npm and PyPI):

import { Webhook } from 'svix';

// rawBody: exact request body (Buffer or string), NOT re-serialised JSON
function verifyHexclave(rawBody, headers, secret = process.env.HEXCLAVE_WEBHOOK_SECRET) {
  const p = headers['svix-id'] ? 'svix' : 'webhook'; // fall back to the Standard Webhooks names
  const [id, timestamp, signature] = ['id', 'timestamp', 'signature'].map((k) => headers[`${p}-${k}`]);
  new Webhook(secret).verify(rawBody, {
    'svix-id': id, 'svix-timestamp': timestamp, 'svix-signature': signature,
    'webhook-id': id, 'webhook-timestamp': timestamp, 'webhook-signature': signature,
  }); // throws on a bad signature or stale timestamp → respond 400
}

The library always enforces a fixed 5-minute timestamp window. Hookdeck retries and replays resend the original svix-timestamp, so the library rejects them once they are more than 5 minutes old. If you receive through Hookdeck and need late retries to pass, use the manual verifier in references/verification.md, which can drop or widen the window. In Express, read the body with express.raw({ type: '*/*' }) so any content type verifies, and parse JSON only after the check.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Event Type and Payload

The body is { type, data }. type is the event name and data is the affected user, team, membership or permission object.

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

The docs elide the other data fields (...); see the per-event API reference pages for each schema.

Common Event Types

EventFired when
user.createdA user is created
user.updatedA user changes
user.deletedA user is deleted
team.createdA team is created
team.updatedA team changes
team.deletedA team is deleted
team_membership.createdA user is added to a team
team_membership.deletedA user is removed from a team
team_permission.createdA permission is granted on a team
team_permission.deletedA permission is removed from a team

These are the 10 documented types; the list may not be exhaustive, so ignore types you don't recognise. See references/overview.md.

Delivery Semantics

Hexclave's docs state no timeout, retry schedule or ordering guarantee; delivery runs on Svix. Return a 2xx quickly, process asynchronously, and deduplicate on svix-id (stable across retries). Return 400 for missing headers or a bad signature. Don't depend on arrival order.

Environment Variables

HEXCLAVE_WEBHOOK_SECRET=whsec_xxxxx   # full value from the endpoint details in the dashboard; 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 hexclave --path /webhooks/hexclave

Set the printed URL as the endpoint URL in the dashboard's Webhooks section.

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →