typescript 74 lines · 7 steps

Verifying Stripe webhooks in NestJS

A NestJS controller that authenticates raw Stripe webhook payloads by signature before dispatching each event to billing logic.

Explained by highlit

NestJS Intermediate webhooks signature-verification event-handling dependency-injection payments

1import {
Controller,
Post,
Headers,
Req,
BadRequestException,
Logger,
8} from '@nestjs/common';
9import { ConfigService } from '@nestjs/config';
10import Stripe from 'stripe';
11import type { RawBodyRequest } from '@nestjs/common';
12import type { Request } from 'express';
13import { BillingService } from './billing.service';
14 
15@Controller('webhooks/stripe')
16export class StripeWebhookController {
private readonly logger = new Logger(StripeWebhookController.name);
private readonly stripe: Stripe;
private readonly webhookSecret: string;
20 
constructor(
  config: ConfigService,
  private readonly billing: BillingService,
) {
  this.stripe = new Stripe(config.getOrThrow('STRIPE_SECRET_KEY'), {
    apiVersion: '2024-06-20',
  });
  this.webhookSecret = config.getOrThrow('STRIPE_WEBHOOK_SECRET');
}
30 
@Post()
async handle(
  @Req() req: RawBodyRequest<Request>,
  @Headers('stripe-signature') signature: string,
) {
  if (!req.rawBody) {
    throw new BadRequestException('Missing raw request body');
  }
39 
  let event: Stripe.Event;
  try {
    event = this.stripe.webhooks.constructEvent(
      req.rawBody,
      signature,
      this.webhookSecret,
    );
  } catch (err) {
    this.logger.warn(`Signature verification failed: ${err.message}`);
    throw new BadRequestException('Invalid Stripe signature');
  }
51 
  switch (event.type) {
    case 'checkout.session.completed':
      await this.billing.activateSubscription(
        event.data.object as Stripe.Checkout.Session,
      );
      break;
    case 'invoice.payment_failed':
      await this.billing.flagPastDue(
        event.data.object as Stripe.Invoice,
      );
      break;
    case 'customer.subscription.deleted':
      await this.billing.cancelSubscription(
        event.data.object as Stripe.Subscription,
      );
      break;
    default:
      this.logger.debug(`Unhandled event type: ${event.type}`);
  }
71 
  return { received: true };
}
74}

01 / 01

STEP 01

Walkthrough

Space play ←→ step click any line

Three takeaways

1Webhook endpoints must verify a cryptographic signature over the raw body to prove requests genuinely come from the provider.
2Signature checks need the untouched raw payload, so the framework must preserve it instead of only exposing parsed JSON.
3Dispatching on event type keeps the endpoint thin while delegating the real work to a dedicated service.

Related explainers

typescript

import { Injectable, UnauthorizedException } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { ExtractJwt, Strategy } from 'passport-jwt';
import { ConfigService } from '@nestjs/config';

How a JWT strategy authenticates in NestJS

authentication jwt passport

Intermediate 7 steps

typescript

import { Injectable } from '@angular/core';
import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent, HttpErrorResponse } from '@angular/common/http';
import { BehaviorSubject, Observable, throwError } from 'rxjs';
import { catchError, filter, take, switchMap } from 'rxjs/operators';

Refreshing auth tokens in an Angular interceptor

http-interceptor token-refresh rxjs

Advanced 8 steps

typescript

import { CanActivate, ExecutionContext, Injectable, UnauthorizedException } from '@nestjs/common';
import { GqlExecutionContext } from '@nestjs/graphql';
import { Reflector } from '@nestjs/core';
import { JwtService } from '@nestjs/jwt';

How a GraphQL auth guard works in NestJS

authentication authorization jwt

Intermediate 7 steps

python

import os
from datetime import timedelta

Class-based config in a Flask app factory

configuration app-factory inheritance

Intermediate 7 steps

typescript

type ResizeCallback = (size: { width: number; height: number }) => void;
 
export function observeResize(callback: ResizeCallback, delay = 150) {
  let timeoutId: ReturnType<typeof setTimeout> | undefined;

Debouncing window resize in TypeScript

debounce closures event-listeners

Intermediate 6 steps

typescript

import { Injectable, Logger, OnApplicationShutdown } from '@nestjs/common';
import { InjectRedis } from '@nestjs-modules/ioredis';
import Redis from 'ioredis';
import { DataSource } from 'typeorm';