Set up webhooks using Next.js

In this guide, we will set up a webhook in Kinde and configure it with a Next.js application.

What you need

Link to this section

• A Kinde account with an available webhook slot (Sign up for free)
• A running Next.js application such as the Next.js starter kit
• A proxy service for local endpoint testing such as localtunnel or Ngrok

Step 1: Create the Kinde webhook route

Link to this section

1. Install the Kinde webhook decoder package with the following command in your terminal:

   npm install @kinde/webhooks

2. Create the webhook route endpoint app/api/webhook/route.ts and add the following code:

   mkdir -p app/api/webhook
   touch app/api/webhook/route.ts

   If you are using the src directory structure, create the file in src/app/api/webhook/route.ts instead.

   app/api/webhook/route.ts

   import { NextResponse } from "next/server";
   import { decodeWebhook } from "@kinde/webhooks";
   
   export async function POST(req: Request) {
     try {
     // Get the token from the request
       const token = await req.text();
   
       // Decode the token
       const decodedToken = await decodeWebhook(
         token,
         process.env.KINDE_ISSUER_URL
       );
   
       if (!decodedToken) {
         return NextResponse.json({ message: "Invalid token" }, { status: 400 });
       }
   
       const {
       data,
       type,
       event_id,
       event_timestamp,
       timestamp,
       source
       } = decodedToken;
   
       // Run further validation if needed based on:
       // - event_id
       // - event_timestamp
       // - timestamp
       // - source
   
     // Handle the event based on the type
       switch (type) {
         case "user.updated":
           // handle user updated event
         // e.g. update database with data.user.email
         console.log(data);
         return NextResponse.json({ status: 200, statusText: "success" });
           break;
         case "user.created":
           // handle user created event
         // e.g. add user to database with data.user.email
         console.log(data);
           return NextResponse.json({ status: 200, statusText: "success" });
           break;
         default:
           // other events that we don't handle
           return NextResponse.json({ status: 200, statusText: "success" });
           break;
       }
   
     } catch (err) {
       if (err instanceof Error) {
         console.error(err.message);
         return NextResponse.json({ message: err.message }, { status: 400 });
       }
     }
     return NextResponse.json({ status: 200, statusText: "success" });
   }

   Whenever an event occurs in Kinde, a POST request is sent to this route endpoint, so that your project can react to the event. For example, refreshing a token or updating data in your database.

   Note that the endpoint needs to be publicly available, with no route protection.

   Handling different event types

   In the example above, we used a switch statement. But you could also set up an endpoint per event type, group them into related endpoints, use a map, or any other method for splitting and managing the events.

3. Deploy your application to the public internet and get a public URL. Your webhook endpoint becomes: https://your-website.com/api/webhook

   See our deployment guides on Netlify and Vercel for more information.

   If you are testing locally, you can follow the local proxy service setup step below.

Step 2: (Alternative path) Set up local proxy service

Link to this section

For this example, we will use localtunnel to create a public proxy URL.

1. Start your development server with the following command:

   npm run dev

2. Open a new terminal window and install the localtunnel package with the following command:

   npm install -g localtunnel

   This will install the localtunnel package globally on your computer.

3. Start the localtunnel server with the following command:

   lt --port 3000

   Replace 3000 with the port number of your development server. This will start the localtunnel server and you will receive a public URL.

   your URL is: https://<random_subdomain>.loca.lt

   Keep this service running during the testing process.

   For more setup instructions, see the localtunnel documentation.

Step 3: Create the webhook in Kinde

Link to this section

1. In Kinde, go to Settings > Webhooks

2. Select Add webhook

3. Give the webhook a name and description

4. Enter the Next.js public endpoint we set up earlier in your project. For example, https://your-website.com/api/webhook

   If you are using an external proxy service to test the endpoint locally, enter the endpoint URL you created in the previous step (e.g., https://<random_subdomain>.loca.lt/api/webhook)

5. Select Add event. A pop-up dialog opens

6. In the dialog that opens, select the events you want to subscribe to. (e.g., user.created, user.updated, etc.) Select Save

7. Select Save to create the webhook

Step 4: Test the webhook

Link to this section

1. Go to your Kinde dashboard > Users

2. Create a new user or update an existing one to trigger the webhook

3. Switch back to the terminal where your server is running and you should see the data in your server console

   POST /api/webhook 200 in 000ms
   {
     user: {
       email: null,
       first_name: 'test',
       id: 'kp_1234567890',
       is_password_reset_requested: false,
       is_suspended: false,
       last_name: 'test',
       organizations: [ [Object] ],
       phone: null,
       username: null
     }
   }

You have successfully set up a webhook in Kinde and tested it.

Next steps

Link to this section

Add Kinde users to your database using the following tutorials:

• Kinde and Prisma
• Kinde and Drizzle