Route handlers for webhooks in NextJS - Cheat Sheet & Quick Revision

Recall & Review

beginner

What is a webhook in web development?

A webhook is a way for an app to provide other applications with real-time information. It sends data automatically when an event happens, like a notification.

beginner

In Next.js, where do you place route handlers for webhooks?

You place route handlers inside the app directory under a folder named after the route, using a file named route.js or route.ts for the handler code.

intermediate

How do you define a POST route handler for a webhook in Next.js 14+?

You export an async function named POST from the route.js file. This function receives the request and returns a response.

intermediate

Why should webhook route handlers verify the request origin?

To ensure the request is from a trusted source and prevent unauthorized or malicious calls to your webhook endpoint.

beginner

What is a common response status code to send after successfully processing a webhook?

A 200 OK status code is commonly sent to acknowledge the webhook was received and processed successfully.

In Next.js route handlers, which function name handles POST requests for webhooks?

A onPost

B getWebhook

C POST

D handlePost

Next.js expects an exported async function named POST to handle POST requests in route handlers.

Where should you place a webhook route handler in Next.js 14+?

A pages/api/webhook.js

B components/webhook.js

C public/webhook.js

D app/webhook/route.js

Next.js 14+ uses the app directory with route.js files for route handlers, so app/webhook/route.js is correct.

What is the main reason to verify webhook requests?

A To prevent unauthorized access

B To speed up the server

C To improve UI design

D To reduce bandwidth

Verifying webhook requests ensures only trusted sources can trigger your webhook, improving security.

Which HTTP status code usually indicates a webhook was processed successfully?

A 200 OK

B 500 Internal Server Error

C 404 Not Found

D 302 Redirect

200 OK signals the webhook was received and handled without errors.

What type of function should you export in Next.js route handlers for webhooks?

A A synchronous function

B An async function

C A class method

D A React component

Route handlers should export async functions to handle asynchronous operations like reading request bodies.

Explain how to create a POST route handler for a webhook in Next.js 14+ and why verifying the request is important.

Think about the file location, function name, and security checks.

Describe the typical response a webhook route handler should send after processing a request successfully.

Focus on status codes and why the sender needs confirmation.

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