If you’re working with Stripe, it’s important to test your webhooks before deploying them to production. In this guide, we’ll go through how to test Stripe webhooks locally in your Next.js project before putting untested webhook code into production.

What are webhooks?

A webhook is an HTTP callback that allows Stripe to send real-time notifications to your server about events that happen in your Stripe account. These notifications are triggered when certain events occur in your Stripe account, such as a successful payment or a failed payment.

When you set up a webhook in Stripe, you provide Stripe with the URL of an endpoint in your application that is capable of receiving these notifications. This is what we are going to build with Next.js in this article.

Stripe then sends an HTTP POST request to the endpoint URL in the Next.js with a JSON payload containing information about the event that triggered the notification. You can find an example of what a Stripe webhook notification looks like here.

With this JSON payload, you can take appropriate actions, such as updating a user’s subscription or sending an email confirmation from your Next.js application.

Installing Next.js app with Typescript

If you haven’t already, you’ll need to install Node.js, and npm or yarn on your machine. Once you’ve done that, you can install Next.js with TypeScript by running the following command in your terminal:

npx create-next-app@latest --ts
# or
yarn create next-app --typescript

This will create a new Next.js project with TypeScript support enabled.

Next, let’s set up the API endpoint for the webook to read.

Setting up the Webhook in Next.js

Before we get started, it’s worth noting that the version of Next.js used in this article is 13.3.0, and assumes you’re using the src/ directory and experimental app/ directory.

Once you’ve installed Next.js, the initial directory structure will look like this:

To create the webhook endpoint in Next.js, we can use the pages/api directory. This directory is reserved for API endpoints, which are server-side only.

To create the Stripe webhook, navigate to the root directory of your Next.js project, and create a new folder and file using the following path pages/api/stripe/webhook.ts.

This will create the necessary endpoint for handling webhook events sent by Stripe. Inside webhook.ts, we can define the route handler function for the webhook endpoint.

Installing dependencies

Before we begin writing the webhook code, we need to install three dependencies:

stripe: The Stripe Node.js library provides convenient access to the Stripe API from applications written in server-side JavaScript.

micro-cors: By default, Next.js API routes are same-origin only. This means that only requests from the same origin as your app will be allowed to access your API routes. However, since Stripe webhook event requests come from a different origin, we need to use Cross-Origin Resource Sharing (CORS) to allow them to reach our API route. To enable CORS in our API route, we will use the micro-cors package.

After you installed this package, if you encounter an error saying, “Could not find a declaration file for module ‘micro-cors'”, you can add the necessary type definitions by running the following command: npm i --save-dev @types/micro-cors. This will install the @types/micro-cors package, which provides the necessary type definitions for TypeScript to recognize the micro-cors module.

raw-body: We need to pass the raw request body in order to compare it with the signature sent by Stripe, and the raw-body package provides a simple way to do this.

It’s worth noting that while we have installed the necessary dependencies for the webhook, you may need additional dependencies for other parts of your custom payment flow. However, as those dependencies are not directly related to the webhook, we won’t cover them in this article.

Now that we have the necessary dependencies installed, we can start writing the webhook code.

Complete Code

Let’s see the complete code first and then walk you through each line of the code to explain what it does and how it works in the following section.

// File path: ./pages/api/stripe/webhook.ts
import type { Stripe } from 'stripe';
import Cors from 'micro-cors';
import getRawBody from 'raw-body';
import { NextApiRequest, NextApiResponse } from 'next';

// Create a Cors middleware with allowed HTTP methods
const cors = Cors({
  allowMethods: ['POST', 'HEAD'],
});

// Retrieve Stripe secret and webhook secret keys from environment variables
const stripeSecret = process.env.STRIPE_SECRET_KEY;
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET_KEY;

// Initialize Stripe
const stripe = require('stripe')(stripeSecret);

// Header name for Stripe signature
const STRIPE_SIGNATURE_HEADER = 'stripe-signature';

// Disable automatic body parsing in Next.js API route
export const config = {
  api: {
    bodyParser: false,
  },
};

// Async function to handle webhook events
const webhookHandler = async (req: NextApiRequest, res: NextApiResponse) => {
  // If the HTTP method is POST
  if (req.method === 'POST') {
    // Retrieve the raw request body
    const rawBody = await getRawBody(req);

    // Retrieve the Stripe signature from the request headers
    const sig = req.headers[STRIPE_SIGNATURE_HEADER]!;

    let event: Stripe.Event;

    try {
      // Construct the event using the Stripe webhook secret
      event = stripe.webhooks.constructEvent(rawBody, sig, webhookSecret);
    } catch (err: any) {
      // If there is an error, log it and return an error response
      console.log(`❌ Error message: ${err.message}`);
      res.status(400).send(`Webhook Error: ${err.message}`);
      return;
    }

    // Successfully constructed event
    // Retrieve the payment intent from the event data object
    // console.log('✅ Success:', event.id);
    const paymentIntent = event.data.object;

    // Handle the event based on its type
    switch (event.type) {
      case 'payment_intent.succeeded':
        // Do something on payment intent success
        // console.log('PaymentIntent was successful!', paymentIntent);
        break;
      case 'payment_method.attached':
        // Do something on payment method attached
        // console.log('PaymentMethod was attached to a Customer!');
        break;
      // ... handle other event types
      default:
        console.log(`Unhandled event type ${event.type}`);
    }

    // Send a response to Stripe to acknowledge the webhook event was received
    res.json({ received: true });
  }
};

// Export the default middleware with CORS enabled and suppress TypeScript type checking for the webhook handler argument
export default cors(webhookHandler as any);

Walk-through

In this section, we will walk through each line of code in the webhook handler function. The webhook handler is an asynchronous function that handles incoming webhook requests from Stripe.

1. Import Dependencies

We begin by importing the necessary dependencies, which include:

Stripe: accessing the Stripe API
Cors: cross-origin resource sharing
getRawBody: retrieving the raw body of an HTTP request
NextApiRequest and NextApiResponse: from Next.js for type-safety.

import type { Stripe } from 'stripe';
import Cors from 'micro-cors';
import getRawBody from 'raw-body';
import { NextApiRequest, NextApiResponse } from 'next';

2. Create Async Function

Next, we create an asynchronous function called webhookHandler that takes in two arguments: req and res. These arguments represent the HTTP request and response objects, respectively. We will use NextApiRequest and NextApiResponse to type these objects.

const webhookHandler = async (req: NextApiRequest, res: NextApiResponse) => {

}

req represents the HTTP request made to our Next.js API routes and it contains information such as:

HTTP method
the request header
query parameters
the request body (raw-body package will be used)

res represents the HTTP response that will be sent back to the client (etc Stripe). It contains methods like:

setting response status code (res.status())
setting response headers (res.setHeader())
sending the response body (res.json(), res.send(), etc.)

For us, we will send the response body (res.json()) notifying Stripe we have correctly received the request.

3. Export `webhookHandler`

After creating the webhookHandler function, we export it at the end of the file.

export default cors(webhookHandler as any);

We are going to export the default value which is the result of calling the cors function with the webhookHandler argument. By using the cors function, the webhookHandler function can be accessed from other domains.

The as any syntax is used to suppress TypeScript type checking for the webhookHandler argument, effectively telling the compiler to treat it as any type. This is often used when working with third-party libraries that may not have TypeScript definitions, or when dealing with dynamic data whose type is not known at compile time.

4. Log req

Let’s log the req object to the console to see what we are getting from the incoming webhook request.

const webhookHandler = async (req: NextApiRequest, res: NextApiResponse) => {
  console.log(req);
}

We will use the Stripe CLI to simulate webhook events (we will need to login to Stripe to use the webhook Dashboard) and test our webhook handler function in our local environment.

5. Install Stripe CLI

To install the Stripe CLI, run the command below. If you have not installed Homebrew yet, you can download it here or find other methods here.

brew install stripe/stripe-cli/stripe

6. Log into Stripe CLI

Once you have installed the Stripe CLI, log in to your Stripe account by running the command below.

stripe login

This will prompt you to open your browser for authentication. Once you grant access through your browser, we can now forward events to our webhook.

7. Start Next.js Dev Server

To forward Stripe events to our webhook, we need to first start the Next.js development server. Run the command below to start the dev server.

yarn dev

This will run our Next.js project on localhost:3000.

⭐️ 8. Forward events to webhook

To forward events to our webhook, run the command below.

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

We are now ready to trigger events with the CLI. To send a payment_intent.succeeded event, open another terminal and run:

stripe trigger payment_intent.succeeded

You will see some messages from the terminal you are running stripe listen like:

To see a list of all supported events, run stripe trigger --help.

9. Check `console.log(req)`

Let’s now take a look at what we’re getting from the requests. Since the webhook is running on the server, we can view the log from the terminal rather than the browser DevTool. Go to the terminal where you’re running yarn dev for your Next.js app and you should see the req object logged.

However, since the req object can be quite lengthy and we only need the method property for now, let’s update the log statement to console.log(req.method) and trigger payment_intent.succeeded again. You should see POST as the req.method value.

Let’s use it for our first condition since we only need to look at requests with the POST method.

import type { Stripe } from 'stripe';
import Cors from 'micro-cors';
import getRawBody from 'raw-body';
import { NextApiRequest, NextApiResponse } from 'next';

const webhookHandler = async (req: NextApiRequest, res: NextApiResponse) => {
  if (req.method === 'POST') {

  }
}

export default cors(webhookHandler as any);

10. Three logics inside `if (req.method === 'POST') {`

Inside the if statement, there are three main tasks that we need to handle:

Constructing the event using the Stripe webhook secret: We will wrap this logic in a try...catch block to handle any potential errors. In case of an error, we’ll send a “webhook error” message back to the client and immediately return to prevent further execution of the code.
Handling the event based on its type: Once the event is successfully constructed, we can perform additional custom logic based on the event type. This is where we can add our own business-specific actions such as registering members or subscribing to email lists.
Sending a response to a client to acknowledge the webhook event was received: Finally, we need to send a response back to the client to acknowledge that the webhook event was received and processed successfully. This response lets the client (in our case, Stripe) know that everything is working as expected.

Now, let’s delve into the first logic and explore how to handle it in code.

11. Construct the event using the Stripe webhook secret

Let’s construct the event using the Stripe webhook secret in the try … catch block.

import type { Stripe } from 'stripe';
import Cors from 'micro-cors';
import getRawBody from 'raw-body';
import { NextApiRequest, NextApiResponse } from 'next';

const cors = Cors({
  allowMethods: ['POST', 'HEAD'],
});

const stripeSecret = process.env.STRIPE_SECRET_KEY;
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET_KEY;
const stripe = require('stripe')(stripeSecret);
const STRIPE_SIGNATURE_HEADER = 'stripe-signature';

const webhookHandler = async (req: NextApiRequest, res: NextApiResponse) => {
  if (req.method === 'POST') {
    const rawBody = await getRawBody(req);
    const sig = req.headers[STRIPE_SIGNATURE_HEADER]!;

    let event: Stripe.Event;

    try {
      event = stripe.webhooks.constructEvent(rawBody, sig, webhookSecret);
    } catch (err: any) {
      
    }
  }
};
export default cors(webhookHandler as any);

To construct the event (line 23), there are several variables we need to define. Let’s take a look at it first.

constructEvent

event = stripe.webhooks.constructEvent(rawBody, sig, webhookSecret);

By passing the raw body, signature, and webhook secret to constructEvent, the stripe library validates the signature and constructs a valid event object. This step ensures the authenticity and integrity of the webhook event received from Stripe. The constructed event object can then be used to access the event’s data and perform further processing or business logic based on the webhook event type.

Let’s take a closer look at the code snippet in more details.

stripe

Let’s initialise the stripe.

const stripe = require('stripe')(stripeSecret);

This line imports the stripe library (CommonJS syntax) and sets it up for use in our codebase by providing the necessary secret key. It enables us to interact with the Stripe API and perform various operations related to payments and other Stripe functionality. Let’s define the stripeSecret.

stripeSecret

const stripeSecret = process.env.STRIPE_SECRET_KEY

We set the STRIPE_SECRET_KEY in the environment variables. In Next JS, we can do it in .env.local file in the root directory. To find your Stripe API keys, check out this documentation.

rawBody

The below line is used to obtain the raw body of the incoming HTTP request.

const rawBody = await getRawBody(req);

By retrieving the raw body of the request, we gain access to the exact data that was sent in the request payload and this is useful when working with webhooks.

sig

Let’s retrieve the Stripe signature from the request headers and assign it to the sig variable. And we are using sig variable to construct the event (line 23).

const sig = req.headers[STRIPE_SIGNATURE_HEADER]!;

We will assign the stripe-signature to the constant variable STRIPE_SIGNATURE_HEADER.

const STRIPE_SIGNATURE_HEADER = 'stripe-signature';

The Stripe signature is typically used for validating the authenticity and integrity of webhook events received from Stripe. By accessing the header value, we can perform signature verification and ensure that the webhook event originated from Stripe.

Just for the side note, the ! at the end of the line is the non-null assertion operator in TypeScript, which tells the compiler that the value retrieved from req.headers[STRIPE_SIGNATURE_HEADER] will not be null or undefined. It is used to assert that the value is present.

webhookSecret

We are going to store the value of the webhookSecret in the environment variable like stripeSecret mentioned above.

const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET_KEY;

And then it will be passed as the third argument to constructEvent to provide the Stripe webhook secret key for verification.

We are ready to test the event. Let’s console.log(event) right below the constructEvent (line 23) and see what we are receiving by running stripe trigger payment_intent.succeeded.

12. Oh oh, 500 error

You might have received 500 error. That’s because, by default, Next.js enables body parsing for API routes, which means it automatically parses the request body based on the specified content type (application/json, application/x-www-form-urlencoded, etc.). However, if the request payload doesn’t match the expected content type or format, it can lead to a parsing error and result in a 500 error response.

To solve this issue, we need to disable the automatic bodyParsing in order to allow us to verify the raw body of a webhook request. Let’s add those lines below.

export const config = {
  api: {
    bodyParser: false,
  },
};

Let’s run stripe trigger payment_intent.succeeded again and now we will receive the event sent from Stripe!

13. Catching errors

When there is an error, let’s log it and return an error response.

try {
  event = stripe.webhooks.constructEvent(rawBody, sig, webhookSecret);
} catch (err: any) {
  res.status(400).send(`Webhook Error: ${err.message}`);
  return;
}

14. Handling the event

Now, let’s proceed to handle the webhook event based on its type. We can use a switch statement to provide different logic for different event types.

switch (event.type) {
  case 'payment_intent.succeeded':
    // Do something on payment intent success
    break;
  case 'payment_method.attached':
    // Do something on payment method attached
    break;
  // ... handle other event types
  default:
    console.log(`Unhandled event type ${event.type}`);
}

Depending on the event type, you can add custom logic inside each case block to handle the event accordingly.

For example, in the payment_intent.succeeded case, we can include the necessary code to register the user or subscribe them to an email list. Similarly, in the payment_method.attached case, we can handle the logic specific to a payment method being attached.

As mentioned above, to see other supported events, run stripe trigger --help.

15. Return 200 response

To acknowledge that the webhook event was received successfully, we can send a 200 response to Stripe.

res.send();

In the code snippet above, res.send() is used to send an empty response body with a 200 status code. This indicates to Stripe that the webhook event was received and processed without any errors. One thing to note is that the response body doesn’t need to contain any content in this case.

16. Verifying the Webhook in Stripe Account

To confirm if the webhook is functioning correctly, log in to your Stripe account and switch to the Test mode. Go to the “Payments” section in the sidebar and select “Overview” to view an overview of all payments.

You should see the details of the successful charge triggered from your local environment.

Enabling the Webhook in Production

Once you have tested the webhook in your local environment and confirmed its functionality, it is time to enable the webhook in your production environment. To do this, you need to add the webhook endpoint URL to the Webhook settings page in your Stripe account. The webhook URL should include the complete domain, such as https://yourdomain.com/api/stripe/webhook.

For more detailed instructions on how to make the webhook live in your Stripe account, please refer to the Stripe documentation here.

Conclusion

Testing Stripe webhooks locally with Next.js offers a convenient and efficient way to ensure seamless integration and expedite development. By following the steps outlined in this guide, you can confidently implement and test webhooks, enhancing the functionality and reliability of your applications.