Skip to main content

API Webhook Delivery System

Build a reliable webhook delivery system with retry logic, signature verification, delivery tracking, and dead letter queue handling.

Fill in the placeholders

Edit the values, then copy your finished prompt.

Your Prompt
prompt.txt
You are a backend systems engineer. Build a production-grade webhook delivery system for a SaaS platform that delivers 1 million events daily to 5,000 webhook subscribers.

Step 1: Design the webhook registration API. Create endpoints for subscribers to register webhook URLs with: target URL (validated and reachable), event types to subscribe to (from 30 available types), a shared secret for signature verification, and optional custom headers. Store registrations in PostgreSQL with a status field (active, paused, disabled). Implement URL validation that rejects private IP ranges and requires HTTPS.

Step 2: Build the event dispatch pipeline. When a domain event bus event occurs, serialize the payload to JSON, compute an HMAC-SHA256 signature using the subscriber's secret, and enqueue the delivery job in Redis + Bull. The job should include: event ID, subscriber ID, payload, signature, attempt number, and scheduled delivery time. Design for 1 million events with fan-out to 5,000 subscribers.

Step 3: Implement the delivery worker that processes webhook jobs. Send an HTTP POST to the subscriber URL with headers: X-Webhook-ID, X-Webhook-Timestamp, X-Webhook-Signature, Content-Type: application/json, and any custom headers. Set a connection timeout of 5 seconds and a read timeout of 30 seconds. Consider HTTP responses 2xx as success, 410 as permanent failure (auto-disable the subscription), and anything else as a transient failure requiring retry.

Step 4: Design the retry strategy using exponential backoff. Schedule retries at intervals: 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours, and 24 hours (total 6 attempts over 24 hours). After exhausting all retries, move the event to a dead letter queue for manual inspection. Track each delivery attempt with timestamp, response status, response body (first 1KB), and latency.

Step 5: Build the webhook management dashboard for subscribers. Show delivery history with success/failure rates, average latency, and recent errors. Provide a test endpoint that sends a sample event to verify the subscriber URL is working. Implement a replay feature that re-delivers events from a specific time range. Allow subscribers to pause and resume their webhooks without losing queued events.

Step 6: Implement health monitoring for webhook endpoints. Track the success rate for each subscriber over the last 24 hours. If the success rate drops below 10%, automatically pause the subscription and notify the subscriber via email. Provide an API endpoint for subscribers to check their webhook health score and recent delivery statistics.

What this prompt does

This prompt makes the AI a backend systems engineer building a webhook delivery system for a [platform_type] platform delivering [events_per_day] events daily to [subscriber_count] subscribers. It covers the registration API, the dispatch pipeline, the delivery worker, the retry strategy, a subscriber dashboard, and health monitoring. Events are signed with an HMAC-[hash_algorithm] signature and enqueued in [queue_system], and the worker treats 2xx as success, 410 as permanent failure, and everything else as retryable.

The structure works because reliable webhook delivery is mostly about handling failure well. The [retry_strategy] backoff schedules [max_retries] attempts over 24 hours at widening intervals, after which events move to a dead letter queue for inspection rather than being silently lost. Signature verification lets subscribers trust the payload came from you and wasn't tampered with, and URL validation that rejects private IP ranges and non-HTTPS targets blocks a common SSRF vector at registration time. The status-based handling treats 410 as a permanent failure that auto-disables the subscription, while the health-monitoring step auto-pauses any subscriber whose success rate over [health_window] falls below [disable_threshold], which keeps failing endpoints from clogging the queue for everyone else.

When to use it

  • You're building outbound webhooks for a platform and want a proven blueprint
  • You need signed payloads subscribers can verify
  • You want retries with backoff and a dead letter queue for exhausted events
  • You need to auto-pause endpoints that keep failing
  • You want a subscriber dashboard showing delivery history and a replay feature
  • You need URL validation that blocks private IPs and requires HTTPS
  • You're fanning out [events_per_day] events to many subscribers and need it to stay reliable

Example output

Expect an implementation walkthrough: a registration API storing subscriptions in [database] with URL validation and a status field, a dispatch pipeline that signs payloads with HMAC-[hash_algorithm] and enqueues to [queue_system], a delivery worker sending POSTs with signature headers, [connect_timeout]/[read_timeout] limits, and status-based handling, a [retry_strategy] schedule of [max_retries] attempts feeding a dead letter queue with per-attempt logging, a subscriber dashboard with delivery history, a test endpoint, and event replay, and health monitoring that auto-pauses below [disable_threshold] and notifies via [notification_method]. It's structured as labeled steps.

Pro tips

  • Validate registered URLs hard — reject private IP ranges and require HTTPS, or your webhook sender becomes an SSRF tool
  • Sign every payload with HMAC-[hash_algorithm] so subscribers can verify authenticity; document the signing string exactly
  • Treat 410 as permanent and auto-disable; retrying a gone endpoint just wastes queue capacity
  • Tune the [retry_strategy] so [max_retries] spans enough time for a subscriber to recover from a real outage
  • Auto-pause below [disable_threshold] and notify the subscriber; a dead endpoint shouldn't drag down delivery for everyone
  • Keep a replay feature — subscribers will eventually need to re-deliver events from a window they missed

Frequently Asked Questions

How do subscribers verify a webhook really came from this system?
Each event is signed with an HMAC-`[hash_algorithm]` signature computed from the payload and the subscriber's shared secret, sent in an `X-Webhook-Signature` header. The subscriber recomputes the signature on their end and compares, which confirms both authenticity and that the payload wasn't tampered with in transit.
What happens to an event that keeps failing delivery?
The system retries using `[retry_strategy]` backoff across `[max_retries]` attempts over 24 hours. If every attempt fails, the event moves to a dead letter queue for manual inspection rather than being dropped, and each attempt's status, response body, and latency are recorded for debugging.
How does it stop a permanently broken endpoint from clogging the queue?
Two mechanisms: a 410 response is treated as permanent failure and auto-disables the subscription, and health monitoring auto-pauses any subscriber whose success rate over `[health_window]` drops below `[disable_threshold]`. Both keep failing endpoints from consuming retry capacity that healthy subscribers need.
Can subscribers re-send events they missed?
Yes. The management dashboard includes a replay feature that re-delivers events from a specified time range, plus a test endpoint to verify the URL works. Subscribers can also pause and resume their webhooks without losing queued events, so a planned outage doesn't drop deliveries.
Engr Mejba Ahmed

Need this built for real?

Engr Mejba Ahmed

AI Developer · Software Engineer

I'm Mejba — I design and ship production AI systems, automations, and full-stack apps. If you want this turned into a working solution for your team, let's talk.

More in API Development Prompts

Engr Mejba Ahmed

Engr Mejba Ahmed

AI assistant · trained on my work

👋

Hey there!

Quick Actions

WhatsApp Direct line to me

Chat on WhatsApp

+880 1723 741224 · Replies within the hour on working days

Popular Questions

Engr Mejba Ahmed is connected
Engr Mejba Ahmed is typing...
Engr Mejba Ahmed avatar

✉ Want me to follow up? Drop your email

Engr Mejba Ahmed avatar

📞 Connect Directly

Choose how you'd like to reach me

WhatsApp

+880 1723 741224

Email

mejba.13@gmail.com

✓ Details sent! I'll get back to you shortly.

Powered by OpenAI

335+

Blog Posts

25

AI Courses

63

Projects

Services & Expertise

Pricing & Process

Learning & Resources

Connect & Support