fusionauth-webhooks

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.

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

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
    const event = JSON.parse(req.body.toString());

    console.log(`Received event: ${event.event.type}`);

    // Handle by event type
    switch (event.event.type) {
      case 'user.create':
        console.log('User created:', event.event.user?.id);
        break;
      case 'user.update':
        console.log('User updated:', event.event.user?.id);
        break;
      case 'user.login.success':
        console.log('User logged in:', event.event.user?.id);
        break;
      case 'user.registration.create':
        console.log('User registered:', event.event.user?.id);
        break;
      default:
        console.log('Unhandled event:', event.event.type);
    }

    res.json({ received: true });
  }
);