Webhooks, Callback URLs, and Security in Next.js – Route Handlers, Proxy, and Access Control

Webhooks in Next.js

To receive event notifications from external services like a CMS, use a Route Handler. The following example listens on /app/webhook/route.ts:

export async function GET(request: NextRequest) {
  const token = request.nextUrl.searchParams.get('token')
  if (token !== process.env.REVALIDATE_SECRET_TOKEN) {
    return NextResponse.json({ success: false }, { status: 401 })
  }

  const tag = request.nextUrl.searchParams.get('tag')
  if (!tag) {
    return NextResponse.json({ success: false }, { status: 400 })
  }

  revalidateTag(tag)
  return NextResponse.json({ success: true })
}

Callback URLs

After completing a third-party flow, users are redirected to a callback URL. You can use this to set a session cookie and redirect the user:

export async function GET(request: NextRequest) {
  const token = request.nextUrl.searchParams.get('session_token')
  const redirectUrl = request.nextUrl.searchParams.get('redirect_url')

  const response = NextResponse.redirect(new URL(redirectUrl, request.url))
  response.cookies.set({
    value: token,
    name: '_token',
    path: '/',
    secure: true,
    httpOnly: true,
  })

  return response
}

Proxy in Next.js

The proxy.ts file can intercept requests before they reach their destination. Only one proxy file is allowed per project.

export const config = {
  matcher: '/api/:function*',
}

export function proxy(request: Request) {
  if (!isAuthenticated(request)) {
    return Response.json({ success: false, message: 'authentication failed' }, { status: 401 })
  }
}

Other examples include:

• Rewriting a path: NextResponse.rewrite()
• Redirecting old paths to new ones: NextResponse.redirect()

Security in Handlers

Header Management

Never pass incoming request headers directly to the response. Response headers are visible to clients.

Rate Limiting

export async function POST(request: Request) {
  const { rateLimited } = await checkRateLimit(request)
  if (rateLimited) {
    return NextResponse.json({ error: 'Rate limit exceeded' }, { status: 429 })
  }
  return new Response(null, { status: 204 })
}

Payload Validation

• Check content type and size
• Sanitize against XSS
• Use timeouts to prevent abuse

Access to Protected Resources

• Always verify credentials before granting access
• Do not rely on proxy alone for authentication
• Remove sensitive data from responses and logs
• Rotate API keys regularly

Preflight Requests

OPTIONS requests ask the server if a request is allowed. If not defined, Next.js adds it automatically and sets the Allow header.

Library Patterns

Some libraries use a factory pattern to generate handlers:

import { createHandler } from 'third-party-library'

const handler = createHandler({ /* options */ })
export const GET = handler
export { handler as POST }

Important Notes

• In Server Components, fetch data directly from the source
• In export mode, only GET handlers with dynamic = 'force-static' are supported
• In serverless environments, handlers are isolated and cannot share state

Conclusion

Next.js provides powerful tools for receiving events, managing sessions, proxying requests, and securing your backend. With Route Handlers, proxy logic, and careful request validation, you can build a robust and secure integration layer for third-party services.