Why Route handlers for webhooks in NextJS? - Purpose & Use Cases

The Big Idea

What if your app could instantly know when something important happens without asking all the time?

The Scenario

Imagine you want your website to react instantly when a payment is made or a form is submitted on another service. You try to check for these events by constantly asking the other service if something new happened.

The Problem

Manually checking for updates means your site is always busy asking questions, wasting resources and slowing down. Plus, you might miss important events or get delayed responses, making your app unreliable.

The Solution

Route handlers for webhooks let your site listen quietly and wait for the other service to send a message only when something important happens. This way, your app reacts instantly and efficiently without wasting effort.

Before vs After

✗ Before

setInterval(() => fetch('https://api.service.com/events'), 5000);

✓ After

export async function POST(request) { /* handle webhook event here */ }

What It Enables

This makes your app instantly responsive to real-world events, improving user experience and saving server resources.

Real Life Example

When a customer completes a payment on Stripe, Stripe sends a webhook to your route handler, which updates the order status immediately without delay.

Key Takeaways

Manual polling wastes resources and can miss events.

Route handlers wait for real-time messages from other services.

This creates fast, reliable, and efficient app reactions.

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