Neon Webhooks

When to Use This Skill

• Setting up Neon Auth webhook handlers
• How do I verify Neon webhook signatures?
• Why is my Neon webhook signature verification failing?
• Understanding Neon Auth event types and blocking vs non-blocking events
• Handling user.created, user.before_create, send.otp, send.magic_link, or phone_number.verified

Verification (core)

Neon Auth signs each webhook with EdDSA (Ed25519) as a detached JWS — there is no shared secret. You verify with the public key published at <NEON_AUTH_URL>/.well-known/jwks.json, selected by the X-Neon-Signature-Kid header. Do not use svix or an HMAC template — neither applies here.

The critical gotcha is the double base64url encoding of the signing input. A naive `${timestamp}.${body}` reconstruction will always fail. Use the raw request body bytes and note X-Neon-Timestamp is in milliseconds.

import crypto from 'node:crypto';