Reacting to Stripe events with webhooks

July 5, 2021

So far, in this series, we’ve interacted with Stripe by sending requests. It was either by requesting the Stripe API directly on the frontend, or the backend. With webhooks, Stripe can communicate with us the other way around.

Webhook is a URL in our API that Stripe can request to send us various events such as information about payments or customer updates. In this article, we explore the idea of Webhooks and implement them into our application to avoid asking Stripe about the status of user’s subscriptions. By doing that, we aim to improve the performance of our application and avoid exceeding rate limits.

Using Stripe webhooks with NestJS#

We aim to develop with Stripe webhooks while running the application on localhost. When working with webhooks, we expect Stripe to make requests to our API. By default, our app can’t be accessed from outside while running locally. Because of that, we need an additional step to test webhooks. To perform it, we need Stripe CLI. We can download it here.

We need to forward received events to our local API. To do it, we need to run the following:

stripe listen --forward-to localhost:3000/webhook

Handling webhook signing secret#

In response, we receive the webhook signing secret. We will need it in our API to validate requests made to our /webhook endpoint.

A valid approach is to keep the webhook secret in our environment variables.

app.module.ts#

import { Module } from "@nestjs/common"
import { ConfigModule } from "@nestjs/config"
import * as Joi from "@hapi/joi"
@Module({
  imports: [
    ConfigModule.forRoot({
      validationSchema: Joi.object({
        STRIPE_WEBHOOK_SECRET: Joi.string(), // ...
      }),
    }), // ...
  ],
  controllers: [],
  providers: [],
})
export class AppModule {}

.env#

STRIPE_WEBHOOK_SECRET=whsec_...
# ...

Accessing the raw body of a request#

NestJS uses the body-parser library to parse incoming request bodies. Because of that, we don’t get to access the raw body straightforwardly. The Stripe package that we need to use to work with webhooks requires it, though.

To deal with the above issue, we can create a middleware that attaches the raw body to the request.

rawBody.middleware.ts#

import { json } from "body-parser"
import { Response } from "express"
 
import RequestWithRawBody from "../stripeWebhook/requestWithRawBody.interface"
 
function rawBodyMiddleware() {
  return json({
    verify: (request: RequestWithRawBody, response: Response, buffer: Buffer) => {
      if (request.url === "/webhook" && Buffer.isBuffer(buffer)) {
        request.rawBody = Buffer.from(buffer)
      }
      return true
    },
  })
}
export default rawBodyMiddleware

Above, we use the RequestWithRawBody interface. We need to define it.

requestWithRawBody.interface.ts#

import { Request } from "express"
 
interface RequestWithRawBody extends Request {
  rawBody: Buffer
}
export default RequestWithRawBody

For the middleware to work, we need to use it in our bootstrap function.

main.ts#

import { NestFactory } from "@nestjs/core"
 
import { AppModule } from "./app.module"
import rawBodyMiddleware from "./utils/rawBody.middleware"
 
async function bootstrap() {
  const app = await NestFactory.create(AppModule)
  app.use(rawBodyMiddleware()) // ...
  await app.listen(3000)
}
bootstrap()

Parsing the webhook request#

When Stripe requests our webhook route, we need to parse the request. To do that successfully, we need three things:

the webhook secret,
the raw request payload,
the stripe-signature request header.

With the stripe-signature header we can verify that the events were sent by Stripe and not by some third party.

When we have all of the above, we can use the Stripe library to construct the event data.

stripe.service.ts#

import { Injectable } from "@nestjs/common"
import { ConfigService } from "@nestjs/config"
import Stripe from "stripe"
@Injectable()
export default class StripeService {
  private stripe: Stripe
  constructor(private configService: ConfigService) {
    this.stripe = new Stripe(configService.get("STRIPE_SECRET_KEY"), {
      apiVersion: "2020-08-27",
    })
  }
  public async constructEventFromPayload(signature: string, payload: Buffer) {
    const webhookSecret = this.configService.get("STRIPE_WEBHOOK_SECRET")
    return this.stripe.webhooks.constructEvent(payload, signature, webhookSecret)
  } // ...
}

The last step in managing the Stripe webhook with NestJS is to create a controller with the /webhook route.

stripeWebhook.controller.ts#

import { Controller, Post, Headers, Req, BadRequestException } from "@nestjs/common"
import StripeService from "../stripe/stripe.service"
import RequestWithRawBody from "./requestWithRawBody.interface"
@Controller("webhook")
export default class StripeWebhookController {
  constructor(private readonly stripeService: StripeService) {}
  @Post()
  async handleIncomingEvents(
    @Headers("stripe-signature") signature: string,
    @Req() request: RequestWithRawBody,
  ) {
    if (!signature) {
      throw new BadRequestException("Missing stripe-signature header")
    }
    const event = await this.stripeService.constructEventFromPayload(signature, request.rawBody) // ...
  }
}

Tracking the status of subscriptions#

One of the things we could do with webhooks is tracking the status of subscriptions. To do that, let’s expand the User entity.

user.entity.ts#

import { Column, Entity, PrimaryGeneratedColumn } from "typeorm"
@Entity()
class User {
  @PrimaryGeneratedColumn()
  public id: number
  @Column({ unique: true })
  public email: string
  @Column({ nullable: true })
  public monthlySubscriptionStatus?: string // ...
}
export default User

We also need a way to set the monthlySubscriptionStatus property. To do that, we need a new method in our UsersService:

users.service.ts#

import { Injectable } from "@nestjs/common"
import { InjectRepository } from "@nestjs/typeorm"
import { Repository, Connection, In } from "typeorm"
import User from "./user.entity"
import { FilesService } from "../files/files.service"
import StripeService from "../stripe/stripe.service"
@Injectable()
export class UsersService {
  constructor(
    @InjectRepository(User)
    private usersRepository: Repository<User>,
  ) {}
  async updateMonthlySubscriptionStatus(
    stripeCustomerId: string,
    monthlySubscriptionStatus: string,
  ) {
    return this.usersRepository.update({ stripeCustomerId }, { monthlySubscriptionStatus })
  } // ...
}

To use the above logic, we need to expand our StripeWebhookController:

stripeWebhook.controller.ts#

import { Controller, Post, Headers, Req, BadRequestException } from "@nestjs/common"
import StripeService from "../stripe/stripe.service"
import RequestWithRawBody from "./requestWithRawBody.interface"
import { UsersService } from "../users/users.service"
import Stripe from "stripe"
@Controller("webhook")
export default class StripeWebhookController {
  constructor(
    private readonly stripeService: StripeService,
    private readonly usersService: UsersService,
  ) {}
  @Post()
  async handleIncomingEvents(
    @Headers("stripe-signature") signature: string,
    @Req() request: RequestWithRawBody,
  ) {
    if (!signature) {
      throw new BadRequestException("Missing stripe-signature header")
    }
    const event = await this.stripeService.constructEventFromPayload(signature, request.rawBody)
    if (
      event.type === "customer.subscription.updated" ||
      event.type === "customer.subscription.created"
    ) {
      const data = event.data.object as Stripe.Subscription
      const customerId: string = data.customer as string
      const subscriptionStatus = data.status
      await this.usersService.updateMonthlySubscriptionStatus(customerId, subscriptionStatus)
    }
  }
}

Above, we had to sort out some TypeScript issues. Currently, Stripe recommends casting to deal with them.

In our flow, Stripe calls our /webhook endpoint and sends us events. We check if they are connected to subscriptions by checking the event.type property. If that’s the case, we can assume that the event.data.object property is a subscription. With that knowledge, we can update the monthlySubscriptionStatus property of a user.

Webhook idempotency#

According to the Stripe documentation, Stripe might occasionally send the same event more than once. They advise us to create a mechanism to guard the application against processing the same event multiple times and making our event processing idempotent.

One way of doing so would be to keep the id of every processed event in the database.

stripeEvent.entity.ts#

import { Entity, PrimaryColumn } from "typeorm"
@Entity()
class StripeEvent {
  @PrimaryColumn()
  public id: string
}
export default StripeEvent

Please notice that above we define a primary column that is not auto-generated. We aim to use the event id from Stripe to populate this column.

stripeWebhook.service.ts#

import { Injectable } from "@nestjs/common"
import { InjectRepository } from "@nestjs/typeorm"
import StripeEvent from "./StripeEvent.entity"
import { Repository } from "typeorm"
@Injectable()
export default class StripeWebhookService {
  constructor(
    @InjectRepository(StripeEvent)
    private eventsRepository: Repository<StripeEvent>,
  ) {}
  createEvent(id: string) {
    return this.eventsRepository.insert({ id })
  }
}

A crucial thing to notice is that the createEvent throws an error when we try to use an id that already exists in the database. We can use it to improve our StripeWebhookController.

stripeWebhook.controller.ts#

import { Controller, Post, Headers, Req, BadRequestException } from "@nestjs/common"
import StripeService from "../stripe/stripe.service"
import RequestWithRawBody from "./requestWithRawBody.interface"
import { UsersService } from "../users/users.service"
import StripeWebhookService from "./stripeWebhook.service"
@Controller("webhook")
export default class StripeWebhookController {
  constructor(
    private readonly stripeService: StripeService,
    private readonly usersService: UsersService,
    private readonly stripeWebhookService: StripeWebhookService,
  ) {}
  @Post()
  async handleIncomingEvents(
    @Headers("stripe-signature") signature: string,
    @Req() request: RequestWithRawBody,
  ) {
    if (!signature) {
      throw new BadRequestException("Missing stripe-signature header")
    }
    const event = await this.stripeService.constructEventFromPayload(signature, request.rawBody)
    if (
      event.type === "customer.subscription.updated" ||
      event.type === "customer.subscription.created"
    ) {
      return this.stripeWebhookService.processSubscriptionUpdate(event)
    }
  }
}

Since our controller keeps growing, let’s move part of the logic to our StripeWebhookService.

stripeWebhook.service.ts#

import { BadRequestException, Injectable } from "@nestjs/common"
import { InjectRepository } from "@nestjs/typeorm"
import StripeEvent from "./StripeEvent.entity"
import { Repository } from "typeorm"
import Stripe from "stripe"
import PostgresErrorCode from "../database/postgresErrorCode.enum"
import { UsersService } from "../users/users.service"
@Injectable()
export default class StripeWebhookService {
  constructor(
    @InjectRepository(StripeEvent)
    private eventsRepository: Repository<StripeEvent>,
    private readonly usersService: UsersService,
  ) {}
  createEvent(id: string) {
    return this.eventsRepository.insert({ id })
  }
  async processSubscriptionUpdate(event: Stripe.Event) {
    try {
      await this.createEvent(event.id)
    } catch (error) {
      if (error?.code === PostgresErrorCode.UniqueViolation) {
        throw new BadRequestException("This event was already processed")
      }
    }
    const data = event.data.object as Stripe.Subscription
    const customerId: string = data.customer as string
    const subscriptionStatus = data.status
    await this.usersService.updateMonthlySubscriptionStatus(customerId, subscriptionStatus)
  }
}

With the above code, our endpoint throws an error when Stripe sends the same event again.

Summary#

In this article, we’ve learned more about Stripe and improved our application by reacting to Stripe events. To do that, we’ve had to implement a webhook that accepts requests from Stripe. When doing so, we’ve started to track changes in the subscription statuses. We’ve also made sure that we don’t parse the same event more than once.