Design a Resilient Webhook Ingestion Endpoint

Get a complete technical design for a webhook ingestion system featuring signature verification, idempotency logic, and a robust retry strategy.

Prompt

Prompt
Act as a Senior Backend Engineer. Design a resilient webhook ingestion endpoint that handles incoming POST requests, verifies authenticity, and manages failures. Follow these rules: 1. Use HMAC-SHA256 for signature verification. 2. Define an idempotency key lifecycle using a Redis-based locking strategy. 3. Provide an exponential backoff schedule including jitter calculations. 4. Include a table showing HTTP response codes for specific failure states. Output format: 1. Security Logic: Detailed steps for signature verification. 2. Idempotency Flow: A numbered list of the request processing lifecycle. 3. Retry Strategy: A table with retry attempt counts and delay times in seconds. 4. Error Handling: A table mapping error types to HTTP status codes. This is for technical architectural purposes only and does not replace production security audits.

Example output

At a glanceRetry delay doubles with each attemptDelay in seconds before each of 5 retry attempts
  • Attempt 1: 1s
  • Attempt 2: 2s
  • Attempt 3: 4s
  • Attempt 4: 8s
  • Attempt 5: 16s

Example for: a payment processing service receiving transaction status updates from Stripe.

1. Security Logic
  • Extract the signature from the X-Signature header.
  • Fetch the shared secret from your secure environment variable storage.
  • Compute the HMAC-SHA256 hash using the raw request body and the shared secret.
  • Compare the computed hash with the provided header signature using a constant-time comparison function to prevent timing attacks.
  • Reject requests immediately if signatures do not match with a 401 Unauthorized response.
2. Idempotency Flow
  1. Check the X-Idempotency-Key header presence.
  2. Attempt to SETNX the key in Redis with a 24-hour TTL.
  3. If the key exists, return the cached result of the previous operation.
  4. If the key is new, process the business logic.
  5. Upon success, store the result in Redis with the same key.
  6. Delete the lock or update the status to completed.
3. Retry Strategy
AttemptDelay (Seconds)Jitter (Seconds)
110.2
220.4
340.8
481.6
5163.2
4. Error Handling
Error TypeHTTP CodeAction
Invalid Signature401Log and drop request
Missing Idempotency Key400Reject request
Database Timeout503Trigger retry logic
Validation Failure422Log and notify developer
Written by AI from this prompt. Your results will vary.

Tips and common edits

Why this works

  • Forces a structured architectural approach to common distributed system failure points.
  • Provides concrete logic for security and idempotency that can be directly implemented.
  • Uses tables for retry and error handling to ensure clarity and quick reference.

Use this prompt in ChatGPT, Claude, or Gemini when you are building a service that must reliably receive and process third-party webhooks. No input is required; the output provides the core architectural blueprint and logic.

Common edits

  • Adjust the Redis TTL based on your specific business requirements for data retention.
  • Modify the HMAC algorithm if your specific third-party provider requires a different standard.

Make it repeatable

Keep using this prompt without pasting it in every time.

Keep exploring

More in Coding