Architecture, Webhook Relay & Localhost Replay
HookSentinel is a developer-first proxy that captures incoming third-party webhooks (Stripe, Shopify, GitHub), buffers failures into a Dead-Letter Queue (DLQ), and streams payloads to localhost with cryptographic signature preservation.
1. Topology & Placement in Architecture
Position HookSentinel between your upstream provider (e.g. Stripe, Shopify) and your backend servers:
2. 3-Minute Quickstart Integration
Open the HookSentinel Console, click Create Route, and configure your target destination (e.g. https://api.yourdomain.com/api/webhooks/stripe). You will receive your dedicated proxy slug URL.
Paste your HookSentinel route URL directly into your Stripe Dashboard (Developers → Webhooks → Add destination):
Stream live production or staging webhooks directly into your local development machine with zero tunnel setup fees:
3. Raw Byte Transparency & HMAC Verification
Most proxy libraries parse JSON and re-serialize it with changed spacing, breaking HMAC signatures like Stripe-Signature or X-Hub-Signature-256.
// Next.js App Router (app/api/webhooks/stripe/route.ts)
import { headers } from 'next/headers';
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
export async function POST(req: Request) {
const body = await req.text(); // Raw buffer preserved untouched by HookSentinel
const signature = (await headers()).get('stripe-signature')!;
try {
const event = stripe.webhooks.constructEvent(
body,
signature,
process.env.STRIPE_WEBHOOK_SECRET!
);
// Process business logic...
return new Response('ok', { status: 200 });
} catch (err: any) {
// If your origin database crashes with HTTP 500, HookSentinel buffers the failure in DLQ!
return new Response(err.message, { status: 500 });
}
}4. Replay Idempotency Best Practice
When you trigger 1-Click Replay from the Dead-Letter Queue to your live server, ensure your webhook consumer is idempotent. Deduplicate incoming events using the provider event ID (e.g. event.id or idempotency-key header) to avoid double-charging or duplicate order fulfillment.