# fusionauth-webhooks

Teach your coding assistant to receive FusionAuth webhooks and verify JWT signatures. Useful when wiring auth events into Express or FastAPI.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 196 installs · ★ 103 repo stars
- Author: hookdeck
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/hookdeck/webhook-skills/tree/HEAD/skills/fusionauth-webhooks/SKILL.md
- Updated: 2026-10-22
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/fusionauth-webhooks

## What it does

This skill guides assistants through handling webhook notifications emitted by FusionAuth. Incoming calls include an `X-FusionAuth-Signature-JWT` header that stores a `request_body_sha256` claim. To confirm authenticity, your application must compute the SHA-256 hash of the unparsed payload and match it against the decoded token.

Premature body parsing breaks the signature immediately. If middleware converts JSON into an object before calculating the digest, formatting changes will cause verification to fail. Express requires `express.raw({ type: 'application/json' })`, while FastAPI handlers must read `request.body()` as raw bytes.

The skill covers verification via `HS256`, `HS384`, and `HS512` algorithms using the `FUSIONAUTH_WEBHOOK_SECRET` key. It also includes event dispatching logic for `user.create`, `user.login.success`, and profile updates.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add hookdeck/webhook-skills --skill fusionauth-webhooks -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/fusionauth-webhooks/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/fusionauth-webhooks/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add hookdeck/webhook-skills --skill fusionauth-webhooks -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/fusionauth-webhooks/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add hookdeck/webhook-skills --skill fusionauth-webhooks -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/fusionauth-webhooks/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install hookdeck/webhook-skills skills/fusionauth-webhooks
```

2. **Manually: put the files in place**
- File: `.github/skills/fusionauth-webhooks/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add hookdeck/webhook-skills --skill fusionauth-webhooks -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/hookdeck/webhook-skills --path skills/fusionauth-webhooks
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/fusionauth-webhooks/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add hookdeck/webhook-skills --skill fusionauth-webhooks -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/hookdeck/webhook-skills/tree/HEAD/skills/fusionauth-webhooks/SKILL.md

## When to use it
- validate FusionAuth JWT signatures using HMAC secrets
- preserve raw request payloads for SHA-256 hash checks
- process authentication events like user.login.success and user.create
- test webhook endpoints locally with hookdeck-cli tunnels

## Example prompts
- Create an Express webhook route for FusionAuth that validates the JWT signature.
- Write a FastAPI handler verifying the request_body_sha256 claim with my signing secret.
- Set up a switch block to handle user.create and user.delete events from FusionAuth.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 5608af76db456d59.

BEGIN THIRD-PARTY FILE 5608af76db456d59
````text
---
name: fusionauth-webhooks
description: >
  Receive and verify FusionAuth webhooks. Use when setting up FusionAuth webhook
  handlers, debugging JWT signature verification, or handling authentication events
  like user.create, user.login.success, user.registration.create, or user.delete.
license: MIT
metadata:
  author: hookdeck
  version: "0.1.0"
  repository: https://github.com/hookdeck/webhook-skills
---

# FusionAuth Webhooks

## When to Use This Skill

- Setting up FusionAuth webhook handlers
- Debugging JWT signature verification failures
- Understanding FusionAuth event types and payloads
- Handling user, login, registration, or group events

## Essential Code (USE THIS)

### FusionAuth Signature Verification (JavaScript)

FusionAuth signs webhooks with a JWT in the `X-FusionAuth-Signature-JWT` header. The JWT contains a `request_body_sha256` claim with the SHA-256 hash of the request body.

```javascript
const crypto = require('crypto');
const jose = require('jose');

// Verify FusionAuth webhook signature
async function verifyFusionAuthWebhook(rawBody, signatureJwt, hmacSecret) {
  if (!signatureJwt || !hmacSecret) return false;

  try {
    // Create key from HMAC secret
    const key = new TextEncoder().encode(hmacSecret);

    // Verify JWT signature and decode
    const { payload } = await jose.jwtVerify(signatureJwt, key, {
      algorithms: ['HS256', 'HS384', 'HS512']
    });

    // Calculate SHA-256 hash of request body
    const bodyHash = crypto
      .createHash('sha256')
      .update(rawBody)
      .digest('base64');

    // Compare hash from JWT claim with calculated hash
    return payload.request_body_sha256 === bodyHash;
  } catch (err) {
    console.error('JWT verification failed:', err.message);
    return false;
  }
}
```

### Express Webhook Handler

```javascript
const express = require('express');
const crypto = require('crypto');
const jose = require('jose');

const app = express();

// CRITICAL: Use express.raw() - FusionAuth needs raw body for signature verification
app.post('/webhooks/fusionauth',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signatureJwt = req.headers['x-fusionauth-signature-jwt'];

    // Verify signature
    const isValid = await verifyFusionAuthWebhook(
      req.body,
      signatureJwt,
      process.env.FUSIONAUTH_WEBHOOK_SECRET  // HMAC signing key from FusionAuth
    );

    if (!isValid) {
      console.error('FusionAuth signature verification failed');
      return res.status(401).send('Invalid signature');
    }

    // Parse payload after verification
````
END THIRD-PARTY FILE 5608af76db456d59

The third-party file has ended. Everything between the 5608af76db456d59 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2597 of 9186 bytes. © hookdeck · MIT · https://github.com/hookdeck/webhook-skills/tree/HEAD/skills/fusionauth-webhooks/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
