Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 38 ยท Projects and Practice

Project: A Webhook Processor

Build a complete, runnable webhook processor with signature verification, replay protection, idempotent storage, a worker queue with retries and a dead-letter list, all on loopback.

In this project you assemble everything from the Webhooks chapter into one small service. It receives signed events over HTTP, rejects forgeries and replays, stores each event once, processes it in the background with retries and parks permanently failing events in a dead-letter list for a human to look at. Everything runs on 127.0.0.1 inside the editor; "Stripe" is a function in the same program that signs events exactly like the real thing.

Requirements

  1. POST /webhooks/stripe verifies Stripe-Signature (HMAC-SHA256 over t.body, 300 second tolerance).
  2. A bad signature returns 400; a good one returns 200 quickly.
  3. Each event id is processed once, however often it is delivered.
  4. Handlers run in a worker. A failing handler is retried up to three times, then moves to the dead-letter list.
  5. Unknown event types are acknowledged and ignored.
flowchart LR
  ST["Fake Stripe"] -->|"signed POST"| V["Verify"]
  V -->|"bad"| X["400"]
  V -->|"good"| D["Dedupe by event id"]
  D --> Q["Queue"]
  Q --> W["Worker with retries"]
  W -->|"3 failures"| DL["Dead letters"]
  W --> OK["Handler effect"]

The pipeline you are building.

Step 1: the core pieces

Node.js Verify, dedupe, queue, work

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Read the output against the requirements: the forged request is rejected, the duplicate adds nothing, the failing event is retried three times and then listed as dead, and the unknown type is ignored.

Step 2: extend it

Choose one or more upgrades and write them yourself:

  • Persist state. Replace the Set and arrays with a database such as node:sqlite, which is available on the runner. Use a PRIMARY KEY on the event id.
  • Backoff. Wait longer between retries (5ms, 10ms, 20ms) instead of a fixed pause.
  • Ordering guard. Store the created time per order and ignore older events.
  • Metrics. Count received, duplicates, failures and dead letters and print a summary.
Node.js Starter for the metrics upgrade

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Production notes

  • Respond within a couple of seconds; do not wait for the worker.
  • A real queue lives outside the web process (Redis, SQS, a database table) so a deploy does not lose jobs.
  • Alert on dead letters and provide a button to retry them.
  • Keep the raw payload and headers for replay and audits.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does the endpoint reply 200 before the handler runs?

    Slow work belongs in a worker; the endpoint only verifies, stores and acknowledges.
  2. 2. What is a dead-letter list for?

    Permanently failing jobs must not vanish; a dead-letter list preserves them for investigation.
  3. 3. In the project, which step stops a duplicate event from running twice?

    The event id is recorded on first sight, so later deliveries are acknowledged but not queued.
  4. 4. Why should the queue live outside the web process in production?

    A durable external queue survives restarts, so accepted events are never lost.

Summary

  • A robust webhook service is verify, dedupe, enqueue, acknowledge, then work.
  • Retries with a cap and a dead-letter list prevent both loops and silent loss.
  • Unknown event types are acknowledged and ignored.
  • Persist state and queues outside the process in production.

Next: Project: A Marketplace Ledger