Route handlers for webhooks in NextJS

Introduction

Route handlers let your Next.js app listen and respond to webhook events from other services. This helps your app react automatically when something happens elsewhere.

You want to receive payment notifications from a payment gateway.

You need to update your database when a user changes info on a third-party app.

You want to trigger actions when a GitHub repository gets a new issue or pull request.

You want to log events from external services in your app.

You want to automate workflows based on external events without user input.

Syntax

NextJS

export async function POST(request) {
  const body = await request.json();
  // handle webhook data here
  return new Response('Webhook received', { status: 200 });
}

Use HTTP methods like POST to receive webhook data.

Parse the request body to access webhook payload.

Examples

Basic POST handler that logs webhook data and responds with OK.

NextJS

export async function POST(request) {
  const data = await request.json();
  console.log('Webhook data:', data);
  return new Response('OK', { status: 200 });
}

Handles specific event types from webhook payload.

NextJS

export async function POST(request) {
  const event = await request.json();
  if (event.type === 'payment_success') {
    // process payment
  }
  return new Response('Processed', { status: 200 });
}

Optional GET handler to check if webhook route is active.

NextJS

export async function GET() {
  return new Response('Webhook endpoint active', { status: 200 });
}

Sample Program

This route handler receives webhook POST requests, logs the event, and responds based on event type. It also handles errors gracefully.

NextJS

export async function POST(request) {
  try {
    const webhookEvent = await request.json();
    console.log('Received webhook event:', webhookEvent);
    // Example: respond differently based on event type
    if (webhookEvent.type === 'user_signup') {
      // handle user signup event
      return new Response('User signup processed', { status: 200 });
    }
    return new Response('Event received', { status: 200 });
  } catch (error) {
    console.error('Error processing webhook:', error);
    return new Response('Bad Request', { status: 400 });
  }
}

Important Notes

Always respond quickly to webhook requests to avoid timeouts.

Validate webhook signatures if the service supports it for security.

Use environment variables to store secret keys for webhook verification.

Summary

Route handlers in Next.js let you receive and process webhook events.

Use POST method to handle incoming webhook data.

Always respond with a status to confirm receipt to the webhook sender.

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