nuxt-webhook-validators

Nuxt Webhook Validators

A simple nuxt module that works on the edge to easily validate incoming webhooks from different services.

• ✨ Release Notes

Features

• 26 Webhook validators
• Works on the edge
• Exposed Server utils

Requirements

This module only works with a Nuxt server running as it uses server API routes (nuxt build).

This means that you cannot use this module with nuxt generate.

Quick Setup

1. Add nuxt-webhook-validators in your Nuxt project

npx nuxi@latest module add webhook-validators

2. Add the module in your nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    'nuxt-webhook-validators'
  ],
})

Server utils

The validator helpers are auto-imported in your server/ directory.

Webhook Validators

All validator helpers are exposed globally and can be used in your server API routes.

The helpers return a boolean value indicating if the webhook request is valid or not.

The config can be defined directly from the runtimeConfig in your nuxt.config.ts:

export default defineNuxtConfig({
  runtimeConfig: {
    webhook: {
      <provider>: {
        <requiredProps>: '',
      }
    }
  }
})

It can also be set using environment variables:

NUXT_WEBHOOK_<PROVIDER>_<REQUIRED_PROPERTY> = ""

Go to playground/.env.example or playground/nuxt.config.ts to see a list of all the available properties needed for each provider.

Supported webhook validators

• Bitbucket
• Brevo
• Cal.com
• Discord
• Docusign
• Dropbox
• Fourthwall
• GitHub
• GitLab
• Heroku
• Hygraph
• Kick
• MailChannels
• Meta
• Mux
• Netlify
• Paddle
• PayPal
• Polar
• Resend
• Shopify
• Slack
• Stripe
• Svix
• Twitch
• Vercel

You can add your favorite webhook validator by creating a new file in src/runtime/server/lib/validators/

Examples

Basic

Validate a GitHub webhook in a server API route.

~~/server/api/webhooks/github.post.ts

export default defineEventHandler(async (event) => {
  const isValidWebhook = await isValidGitHubWebhook(event)

  if (!isValidWebhook) {
    throw createError({ status: 401, message: 'Unauthorized: webhook is not valid' })
  }

  // Some logic...

  return { isValidWebhook }
})

Reading the request body

Make sure to read the body after validating the webhook, as most validators rely on a caching/cloning of the raw body to compute the signature and validate the webhook.

export default defineEventHandler(async (event) => {
  const isValidWebhook = await isValidGitHubWebhook(event)

  if (!isValidWebhook) {
    throw createError({ status: 401, message: 'Unauthorized: webhook is not valid' })
  }

  // Make sure to read the body after validating the webhook
  const body = await readBody(event)

  return { isValidWebhook }
})

Development

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Run typecheck
npm run test:types

# Release new version
npm run release