# 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.

```javascript
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
}

```

Enforce a timestamp tolerance (e.g. 5 minutes) against `X-Neon-Timestamp` to block replays, and use `X-Neon-Event-Id` for idempotency.

> For complete handlers with route wiring, event dispatch, JWKS caching, and tests, see:
> 
> * [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/neon-webhooks/examples/express/)
> * [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/neon-webhooks/examples/nextjs/)
> * [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/neon-webhooks/examples/fastapi/)

## Request Headers

| Header | Description |
| --- | --- |
| `X-Neon-Signature` | Detached JWS, format `header..signature` (empty middle section) |
| `X-Neon-Signature-Kid` | Key ID — select the matching key from the JWKS |
| `X-Neon-Timestamp` | Unix timestamp in milliseconds (replay protection) |
| `X-Neon-Event-Type` | Event type, e.g. `user.created` |
| `X-Neon-Event-Id` | Event UUID — use for idempotency |
| `X-Neon-Delivery-Attempt` | Delivery attempt number (`1`, `2`, or `3`) |

## Common Event Types

| Event | Type | Fires When |
| --- | --- | --- |
| `send.otp` | Blocking | A one-time passcode needs delivering (custom OTP delivery) |
| `send.magic_link` | Blocking | A magic link needs delivering (custom link delivery) |
| `user.before_create` | Blocking | Just before a user is written — validate/reject signups |
| `user.created` | Non-blocking | A user account has been created (sync to CRM/analytics) |
| `phone_number.verified` | Non-blocking | A user's phone number has been verified |

Blocking events pause the auth flow until your endpoint returns a `2xx` (or times out) — respond fast and do heavy work asynchronously.

> For full event reference, see [Neon Auth webhooks](https://neon.com/docs/auth/guides/webhooks).

## Environment Variables

```bash
NEON_AUTH_URL=https://your-neon-auth-domain.com   # JWKS fetched from ${NEON_AUTH_URL}/.well-known/jwks.json

```

There is no signing secret — verification uses the public JWKS, so nothing sensitive is stored.

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 neon --path /webhooks/neon

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/neon-webhooks/references/overview.md) - Neon Auth webhook concepts and events
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/neon-webhooks/references/setup.md) - Configure webhooks via the Neon API
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/neon-webhooks/references/verification.md) - Ed25519 / detached JWS verification details and gotchas