---
title: Build a webhook event viewer for local debugging
description: Inspect verified Vercel webhook events in a local viewer with redacted records, duplicate detection, and reproducible fixtures.
url: "https://vercel.com/kb/prompts/build-webhook-event-viewer"
last_updated: 2026-11-07
related_resources:
  "[Set up Vercel webhooks](https://vercel.com/docs/webhooks)": "Choose events and understand the webhook envelope and secret."
  "[Vercel webhook API reference](https://vercel.com/docs/webhooks/webhooks-api)": "Verify signatures and handle webhook responses and delivery retries."
---

# Build a webhook event viewer for local debugging

Inspect verified Vercel webhook events in a local viewer with redacted records, duplicate detection, and reproducible fixtures.

Build a local viewer for Vercel webhook events so you can inspect event types and delivery outcomes while developing an integration. Start with signed synthetic fixtures before connecting a live source.

Use an empty workspace or open the project that will receive events. Live testing needs a webhook secret and a reachable receiver, while the viewer needs access controls. Continuing with an agent supplies no repository, secret, or tunnel.

You get a bounded event list with redacted details and duplicate handling. The viewer observes deliveries; it does not replay payloads, deploy projects, or trigger business actions.

## Agent prompt

```text
Build a local debugging app that receives verified Vercel webhook events and shows a bounded, redacted event history. It must observe deliveries without replaying them or triggering business actions.

Read repository instructions and inspect the framework, package manager, persistence, authentication, UI patterns, and tests. Reuse them. If an intended existing project is missing, ask me to open or import it. Otherwise an empty workspace can use a small Next.js app. Start with signed synthetic Vercel event fixtures and a local test secret. Never silently bypass signature checks for fixture mode.

Use the current Vercel webhook documentation to verify the signature format, event envelope, and delivery behavior. Enforce a request byte limit before buffering. Authenticate the exact raw request bytes with the configured webhook secret before parsing JSON. Validate signature encoding and length, then compare in constant time; reject absent secrets and invalid signatures. Validate the envelope and allow only the event types chosen for this viewer.

Persist a minimal allowlisted record containing the event identifier, type, timestamps, processing outcome, and selected non-sensitive fields. Redact before persistence, logging, or display. Do not store request headers, signatures, tokens, or arbitrary raw payloads. Scope deduplication to the configured source and event ID with an atomic uniqueness constraint. A duplicate should return an accepted response without creating another event; storage failure must not return success. Acknowledge successful durable recording promptly, with no detached in-memory work after the response.

Build a paginated list and detail view with event-type filtering, readable timestamps, empty/error states, and keyboard access. Render values as text, never HTML. Set a bounded retention policy and keep fixture data distinguishable from live events. Gate the viewer and read API with authentication, or make the initial app explicitly loopback-only and refuse public operation until access control exists. If deployed later, require durable storage suitable for Vercel Functions instead of local files or process memory.

Test signed valid input, altered raw bytes, malformed signatures, missing configuration, oversized bodies, duplicate deliveries arriving concurrently, storage failure followed by retry, redaction, and unauthorized viewer access. Use local fixtures and existing tools; do not register a webhook or open a tunnel without approval.

Report actual tests, local run steps, required configuration, and persistence/retention limits. Ask before exposing the receiver publicly, connecting live events, creating services, or deploying.
```

## Related resources

- [Set up Vercel webhooks](https://vercel.com/docs/webhooks): Choose events and understand the webhook envelope and secret.

- [Vercel webhook API reference](https://vercel.com/docs/webhooks/webhooks-api): Verify signatures and handle webhook responses and delivery retries.

## Try other prompts

- [Protect a public API with verified rate limits](/kb/prompts/protect-public-api-from-abuse): Add server-enforced limits to one API route, test rejection and recovery, and document the Firewall configuration it needs.

- [Build a scheduled data sync that recovers from failures](/kb/prompts/build-scheduled-data-sync): Create a bounded data sync with authenticated scheduling, durable checkpoints, and tests for retries, duplicate runs, and recovery.

## Reference Architecture

Choose a stack and work through the decisions behind it, with curated documentation, guides, templates, and courses to help you build.

- [Agent stack](/kb/architecture/agents): Build and operate agents with models, tools, and durable workflows.
- [Web applications](/kb/architecture/web): Choose rendering, data, authentication, and caching approaches.
- [Backends](/kb/architecture/backends): Choose a runtime, connect services, and run background work.

[Browse all stacks](/kb/architecture)