Next.js Webhook Handler Code Examples
Scope: This guide provides copy-paste webhook handler examples for Next.js. For a comprehensive overview of patterns and best practices, see the Complete Guide to Webhooks in Next.js.
Setting up webhook handlers in Next.js starts simple enough — create an API route, parse the payload, handle the event. The initial Next.js webhook example usually works fine during development and early production use.
The problems emerge gradually. Webhook deliveries that should have triggered business logic but didn’t. Retries creating duplicate processing without clear audit trails. Failures that are difficult to reproduce or replay safely. What began as a straightforward API route slowly accumulates debugging complexity and reliability concerns.
Most developers end up treating webhook handlers as “working but fragile” — code they’d prefer not to touch again. When this keeps happening, it’s usually less about handler logic and more about missing persistence and visibility between the provider and your app.
Why webhook deliveries fail silently in Next.js
Next.js webhook handlers fail in predictable ways that are difficult to debug after the fact. The serverless execution model means your handler might timeout, throw an exception, or return successfully while the business logic silently fails somewhere in the request lifecycle.
Webhook providers typically retry based on HTTP status codes, but they can’t see into your application logic. A handler might return 200 while failing to save to the database, process a payment update, or trigger downstream systems. The provider considers this delivered successfully and moves on.
Debugging these issues usually involves correlating provider delivery logs with your application logs, trying to reproduce the exact payload and timing, and guessing whether the failure was transient or systematic. Local development behaves differently than production, making reproduction unreliable.
If this is a low-volume app where occasional missed events are acceptable, this complexity may not matter yet.
Next.js serverless execution constraints
The Next.js serverless execution model creates specific webhook reliability challenges. API routes have limited execution time, cold starts introduce latency, and the request-response cycle must complete within platform constraints.
Webhook processing often involves multiple external API calls, database writes, or complex business logic that may exceed serverless timeout limits. When a handler times out, the provider receives no response and will retry, but you have no visibility into how far the processing got before the timeout occurred.
Edge runtime environments add another layer of constraints around available APIs and execution context. What works in the Node.js runtime might behave differently at the edge, and debugging these differences usually requires production traffic to surface.
The framework abstraction hides infrastructure concerns that matter for webhook reliability — connection pooling, request queuing, and failure modes that are invisible until they cause problems.
How HookRelay decouples delivery from processing
HookRelay acts as a buffer between webhook providers and your Next.js application. Instead of providers delivering directly to your API routes, they send to HookRelay endpoints that handle delivery reliability separately from your business logic.
HookRelay tracks delivery attempts and provides visibility into failures, retries, and payload inspection without requiring changes to your existing handler logic. The provider’s retry concerns become separate from your application’s processing concerns.
Instead of Stripe retrying your API route directly and potentially causing duplicate processing, HookRelay receives the webhook, stores it persistently, and forwards it to your application with controllable retry behavior and failure tracking.
What this looks like in a Next.js app
- Point the webhook provider at a HookRelay endpoint instead of your API route
- HookRelay forwards events to your Next.js handler and records delivery attempts
- Failed deliveries remain visible and replayable after you fix the handler
- Retries happen with backoff and inspection outside your serverless execution limits
- Duplicate events are identifiable through persistent delivery history
Stripe webhook retry behavior and Next.js
Stripe webhooks include signature verification, automatic retries with exponential backoff, and idempotency concerns that interact poorly with Next.js serverless constraints. Stripe will retry failed deliveries for up to 3 days, but each retry looks identical to your handler.
When a Stripe webhook times out in a Next.js API route, Stripe logs this as a delivery failure and schedules a retry. Your application may have partially processed the event before timing out, creating scenarios where retries cause duplicate processing or inconsistent state.
Stripe’s webhook delivery attempts don’t provide visibility into your application’s processing state. A failed signature verification, database timeout, or downstream API failure all look the same from Stripe’s perspective — your endpoint didn’t return 200 quickly enough.
Tracking Stripe webhook failures outside your Next.js app provides the visibility needed to distinguish between transient infrastructure issues and systematic handler problems.
When webhook reliability infrastructure makes sense
This architectural approach becomes useful once webhooks are operationally important — when missed or duplicated events create customer-facing problems or require manual intervention to resolve.
Early prototypes and low-volume applications often don’t need this complexity. If webhook failures are rare and their impact is acceptable, the additional infrastructure may not be justified.
The decision usually comes down to whether you want webhook delivery concerns mixed with your business logic, or separated into dedicated infrastructure that can be debugged and managed independently.
Teams typically adopt webhook reliability tooling when they’re tired of debugging webhook issues through application logs and want replay capability that doesn’t require rebuilding events from scratch.