Stripe Webhook Security

Security Boundaries

Webhook endpoints face unique security challenges: they receive POST requests from the public internet, process financial data, and must be available 24/7. Every layer must be hardened.

Signature Verification Is the Firewall

The Stripe-Signature header + raw body HMAC check is the primary security boundary. Without it, any attacker can forge webhook events and manipulate subscription state.

Hard rules:

• Verify the signature on EVERY webhook request, no exceptions
• Use the raw, unparsed body — never the JSON-parsed result
• Use the correct webhook signing secret (whsec_...), not the API key (sk_...)
• Reject requests missing the stripe-signature header with 400
• Log failed verification attempts (without exposing the secret or raw body)

try {
  event = stripe.webhooks.constructEvent(rawBody, sig, env.STRIPE_WEBHOOK_SECRET);
} catch (err) {
  // Log warning — NEVER log the secret, raw body, or full signature
  request.log.warn({ error: (err as Error).message }, 'Webhook signature failed');
  return reply.status(400).send({ error: 'Invalid signature' });
}

Rate Limiting

Apply layered rate limits using @fastify/rate-limit:

Global Rate Limit

fastify.register(rateLimitPlugin, {
  max: 1000,
  timeWindow: '1 minute',
});

Webhook-Specific Rate Limit

Stripe can burst webhook deliveries during batch operations. Set webhook limits higher than API limits but still bounded:

fastify.register(async function webhookContext(instance) {
  instance.register(rateLimitPlugin, {
    max: 500,
    timeWindow: '1 minute',
    keyGenerator: () => 'stripe-webhooks', // Single bucket for all webhook traffic
  });

  instance.post('/stripe', stripeWebhookHandler);
}, { prefix: '/webhooks' });

Authentication Endpoint Rate Limit

// Prevent brute-force credential stuffing
fastify.register(rateLimitPlugin, {
  max: 5,
  timeWindow: '1 minute',
  keyGenerator: (request) => request.ip,
  routeConfig: { rateLimit: { max: 5 } },
});

404 Rate Limit

// Prevent automated scanning for valid routes
fastify.setNotFoundHandler({
  preHandler: fastify.rateLimit({ max: 10, timeWindow: '1 minute' }),
}, (request, reply) => {
  reply.status(404).send({ error: 'Not found' });
});

Secret Management

Secrets That Must Never Leave the Server

Validation at Startup

Validate all secrets exist and have the correct format before the application starts. See the stripe-zod-contracts skill for the full envSchema definition. The key principle: fail fast — do not start the server with missing or malformed secrets. Use Zod's regex and startsWith validators to enforce format (sk_test_, whsec_, etc.).

### What Must Never Be Committed

- `.env` files containing real secrets
- Stripe API keys in source code
- Webhook signing secrets in configuration files
- JWT private keys in the repository

Add to `.gitignore`:

.env .env.* !.env.example

Provide `.env.example` with placeholder values for documentation.

## Log Redaction

### What to Redact

- Stack traces in production (expose internal paths)
- JWT token values in authentication logs
- Stripe customer IDs in public-facing error messages
- Full webhook payloads (may contain PII)
- Internal database IDs in API responses

### Pino Logger Configuration

const fastify = Fastify({ logger: { level: process.env.NODE_ENV === 'production' ? 'info' : 'debug', redact: { paths: [ 'req.headers.authorization', 'req.headers["stripe-signature"]', 'req.body.card', 'req.body.email', ], censor: '[REDACTED]', }, }, });

### Response Schema as Security Filter

Use Fastify response schemas to automatically strip internal fields:

const subscriptionResponseSchema = z.object({ id: z.string(), planName: z.string(), status: z.string(), currentPeriodEnd: z.number(), // Internal fields like stripe_customer_id are NOT in this schema // — Fastify's serializer automatically excludes them });

## Webhook Endpoint Isolation

Register webhook routes in a separate Fastify plugin context:

1. **No JWT authentication** — webhooks authenticate via Stripe signature, not JWT
2. **No CORS** — webhooks are server-to-server, browsers never call them
3. **Custom body parser** — raw body preservation instead of JSON parsing
4. **Separate rate limits** — higher limits than user-facing API

// Root application fastify.register(corsPlugin); // CORS for browser clients fastify.register(jwtAuthPlugin); // JWT for API routes fastify.register(billingApiRoutes); // Protected billing API

// Isolated webhook context — no CORS, no JWT, custom parser fastify.register(webhookRoutes, { prefix: '/webhooks' });

## Abuse Prevention Checklist

- [ ] Stripe signature verification on every webhook request
- [ ] Rate limiting on webhook endpoints
- [ ] Rate limiting on authentication endpoints
- [ ] All secrets validated at startup with Zod
- [ ] No secrets in source control
- [ ] Log redaction configured for production
- [ ] Response schemas strip internal fields
- [ ] Webhook routes isolated from API routes
- [ ] Error responses do not expose internal details
- [ ] Failed verification logged without sensitive data

## Related Skills

- **stripe-zod-contracts** — For the full `envSchema` with all secret format validators
- **stripe-webhook-handling** — For signature verification implementation details
- **stripe-webhook-best-practices** — For the complete 5-rule framework