neon-webhooks

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';

// X-Neon-Signature is a detached JWS: "header..signature" (empty middle section).
async function verifyNeonWebhook(rawBody, headers, jwksUrl) {
  const [headerB64, emptyPayload, signatureB64] = headers['x-neon-signature'].split('.');
  if (emptyPayload !== '') throw new Error('Expected detached JWS (header..signature)');

  const jwks = await fetch(jwksUrl).then((r) => r.json());          // cache these keys by kid
  const jwk = jwks.keys.find((k) => k.kid === headers['x-neon-signature-kid']);
  if (!jwk) throw new Error('Signing key not found in JWKS');
  const publicKey = crypto.createPublicKey({ key: jwk, format: 'jwk' });

  // Double base64url: signingInput = header + "." + b64url(timestamp + "." + b64url(rawBody))
  const payloadB64 = Buffer.from(rawBody, 'utf8').toString('base64url');
  const inner = `${headers['x-neon-timestamp']}.${payloadB64}`;      // timestamp is in MILLISECONDS
  const signingInput = `${headerB64}.${Buffer.from(inner, 'utf8').toString('base64url')}`;

  const ok = crypto.verify(null, Buffer.from(signingInput), publicKey,
    Buffer.from(signatureB64, 'base64url'));                          // null alg = Ed25519
  if (!ok) throw new Error('Invalid signature');
  return JSON.parse(rawBody);                                         // parse only AFTER verifying
}