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.createdorteam_membership.createdevents? - Why is my Hexclave webhook verification failing?
Verification (core)
| Header | Value |
|---|---|
svix-id | Identifies the message; retries reuse it |
svix-timestamp | Unix seconds |
svix-signature | One 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
| Event | Fired when |
|---|---|
user.created | A user is created |
user.updated | A user changes |
user.deleted | A user is deleted |
team.created | A team is created |
team.updated | A team changes |
team.deleted | A team is deleted |
team_membership.created | A user is added to a team |
team_membership.deleted | A user is removed from a team |
team_permission.created | A permission is granted on a team |
team_permission.deleted | A 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
- references/overview.md - Event catalog and payload shape
- references/setup.md - Create the endpoint, find the secret, test
- references/verification.md - Library and manual verification, gotchas, debugging