Route handlers for webhooks in NextJS - Mini Project: Build & Apply

Route handlers for webhooks

📖 Scenario: You are building a Next.js app that needs to receive data from an external service using webhooks. Webhooks send data to your app via HTTP POST requests. You want to create a route handler that listens for these webhook POST requests and processes the data.

🎯 Goal: Create a Next.js route handler that accepts POST requests at /api/webhook. It should read the JSON body sent by the webhook and respond with a success message.

📋 What You'll Learn

Create a POST route handler in Next.js using the new App Router conventions

Parse the JSON body from the incoming request

Return a JSON response confirming receipt

Use only functional code patterns recommended in Next.js 14+

Do not use deprecated API routes or class components

💡 Why This Matters

🌍 Real World

Webhooks are widely used to let external services notify your app about events like payments, form submissions, or updates. Handling webhooks correctly is essential for real-time integrations.

💼 Career

Many web developer roles require building or maintaining webhook endpoints to integrate with third-party APIs and services securely and reliably.

1

Create the API route file

Create a file named app/api/webhook/route.ts and export an async function called POST that takes a Request object as a parameter.

NextJS

// Create the file and export async function POST(request: Request) {}

// Your code here

Hint

This is the new way to create API routes in Next.js 14+ using the App Router.

2

Parse JSON body from the request

Inside the POST function, use await request.json() to read the JSON body and store it in a variable called data.

NextJS

export async function POST(request: Request) {
  // Parse JSON body from request
  // Your code here
}

Hint

Use await request.json() to get the webhook data sent as JSON.

3

Return a JSON response confirming receipt

Return a new Response object with a JSON string body containing { message: 'Webhook received' } and set the Content-Type header to application/json.

NextJS

export async function POST(request: Request) {
  const data = await request.json();
  // Return JSON response confirming receipt
  // Your code here
}

Hint

Use new Response() to send back JSON with proper headers.

4

Complete the webhook route handler

Add a comment inside the POST function that says // Process webhook data here just after parsing the JSON body to indicate where webhook logic would go.

NextJS

export async function POST(request: Request) {
  const data = await request.json();
  // Your code here
  return new Response(JSON.stringify({ message: 'Webhook received' }), {
    headers: { 'Content-Type': 'application/json' }
  });
}

Hint

This comment shows where you would add your webhook processing logic.

Practice

1. What HTTP method should you use in a Next.js route handler to receive webhook events?

easy

A. GET

B. POST

C. PUT

D. DELETE

Solution

1. Step 1: Understand webhook data sending

   Webhooks send data to your server, usually using the POST method to submit event payloads.

2. Step 2: Match HTTP method in Next.js route handler

   To receive webhook data, your Next.js route handler must listen for POST requests.

3. Final Answer:

   POST -> Option B

4. Quick Check:

   Webhook data uses POST = POST [OK]

Hint: Webhooks send data with POST method, always listen for POST [OK]

Common Mistakes:

• Using GET method which does not carry webhook payload
• Using PUT or DELETE which are not standard for webhooks
• Not specifying method and allowing all methods

2. Which of the following is the correct syntax to export a POST route handler in Next.js for a webhook?

easy

A. export function POST(req) { return new Response('ok') }

B. export default function handler(req, res) { res.send('ok') }

C. export async function get(req) { return Response.json('ok') }

D. export function postHandler(req, res) { res.json('ok') }

Solution

1. Step 1: Identify Next.js route handler syntax

   Next.js route handlers export named functions matching HTTP methods, e.g., export function POST(req) { ... }

2. Step 2: Check each option for correct syntax

   export function POST(req) { return new Response('ok') } uses correct named export POST with a Request object and returns a Response. Others use Express style or wrong method names.

3. Final Answer:

   export function POST(req) { return new Response('ok') } -> Option A

4. Quick Check:

   Named export POST with Request and Response = export function POST(req) { return new Response('ok') } [OK]

Hint: Use named export POST(req) returning Response for webhook handlers [OK]

Common Mistakes:

• Using default export instead of named export for POST
• Using lowercase 'post' instead of uppercase 'POST'
• Mixing Express.js syntax with Next.js route handlers

3. Given this Next.js route handler code for a webhook, what will be the HTTP status code of the response?

export async function POST(req) {
  const data = await req.json();
  if (data.event === 'ping') {
    return new Response('pong', { status: 200 });
  }
  return new Response('ignored', { status: 204 });
}

medium

A. Always 204

B. Always 200

C. 200 if event is 'ping', otherwise 204

D. 500 on error

Solution

1. Step 1: Analyze conditional response

   If the JSON body has event equal to 'ping', the handler returns status 200 with 'pong'. Otherwise, it returns status 204 with 'ignored'.

2. Step 2: Understand status codes

   Status 200 means OK, 204 means No Content (successful but no response body expected). The code matches these conditions exactly.

3. Final Answer:

   200 if event is 'ping', otherwise 204 -> Option C

4. Quick Check:

   Conditional status 200 or 204 = 200 if event is 'ping', otherwise 204 [OK]

Hint: Check conditions returning different status codes in route handler [OK]

Common Mistakes:

• Assuming always 200 regardless of condition
• Confusing 204 with error status
• Ignoring async/await for JSON parsing

4. Identify the error in this Next.js webhook route handler code:

export async function POST(req) {
  const body = await req.json;
  return new Response('Received');
}

medium

A. No error, code is correct

B. Response should be JSON, not plain text

C. POST function must be synchronous

D. Missing parentheses when calling req.json()

Solution

1. Step 1: Check usage of req.json

   req.json is a function and must be called with parentheses: req.json()

2. Step 2: Verify other parts

   Returning new Response with plain text is valid; async function is allowed. So only missing parentheses is error.

3. Final Answer:

   Missing parentheses when calling req.json() -> Option D

4. Quick Check:

   req.json() requires parentheses = Missing parentheses when calling req.json() [OK]

Hint: Always call req.json() as a function with parentheses [OK]

Common Mistakes:

• Forgetting parentheses on req.json causing runtime error
• Assuming POST must be synchronous
• Thinking Response must be JSON always

5. You want to create a Next.js webhook route handler that only accepts POST requests, verifies a secret token in headers, and responds with status 401 if unauthorized. Which code snippet correctly implements this?

hard

A. export async function POST(req) {
const token = req.headers.get('x-secret-token');
if (token !== 'mysecret') {
return new Response('Unauthorized', { status: 401 });
}
return new Response('Webhook received', { status: 200 });
}

B. export function GET(req) {
const token = req.headers['x-secret-token'];
if (token !== 'mysecret') {
return new Response('Unauthorized', { status: 401 });
}
return new Response('Webhook received', { status: 200 });
}

C. export async function POST(req, res) {
if (req.headers['x-secret-token'] !== 'mysecret') {
res.status(401).send('Unauthorized');
} else {
res.status(200).send('Webhook received');
}
}

D. export async function POST(req) {
const token = req.headers.get('secret-token');
if (token === 'mysecret') {
return new Response('Unauthorized', { status: 401 });
}
return new Response('Webhook received', { status: 200 });
}

Solution

1. Step 1: Check method and header access

   Webhook must use POST method and access headers with req.headers.get('header-name'). export async function POST(req) { const token = req.headers.get('x-secret-token'); if (token !== 'mysecret') { return new Response('Unauthorized', { status: 401 }); } return new Response('Webhook received', { status: 200 }); } uses POST and correct header name 'x-secret-token'.

2. Step 2: Verify authorization logic and response

   If token mismatches, respond 401 Unauthorized; else respond 200 OK. export async function POST(req) { const token = req.headers.get('x-secret-token'); if (token !== 'mysecret') { return new Response('Unauthorized', { status: 401 }); } return new Response('Webhook received', { status: 200 }); } correctly implements this logic.

3. Final Answer:

   Option A code snippet -> Option A

4. Quick Check:

   POST + req.headers.get + 401 on bad token = export async function POST(req) { const token = req.headers.get('x-secret-token'); if (token !== 'mysecret') { return new Response('Unauthorized', { status: 401 }); } return new Response('Webhook received', { status: 200 }); } [OK]

Hint: Use POST, req.headers.get, and return 401 if token invalid [OK]

Common Mistakes:

• Using GET instead of POST for webhook
• Accessing headers as object instead of using .get()
• Reversing authorization logic (401 on valid token)
• Using Express style req, res in Next.js route handlers