HookRelay

Outbound webhooks need a reliability layer between accepting an event and a receiver actually processing it. Network failures, timeouts, transient HTTP errors, and duplicate requests are normal parts of that path.

HookRelay is a production-style local reference implementation of that layer. It accepts events idempotently, commits delivery state to PostgreSQL, schedules asynchronous work through Redis and BullMQ, signs outgoing requests, and records every attempt.

The Fastify API validates endpoint and event input with Zod. Event acceptance creates an event and its initial delivery in one PostgreSQL transaction, before queue scheduling is attempted.

BullMQ carries the durable deliveryId. The worker reloads canonical event and endpoint data from PostgreSQL, starts a persisted attempt, signs and sends the request, classifies the response, and writes the outcome back to the database.

The dashboard reads deliveries, attempt timelines, retry scheduling, latency, failures, and replay lineage through the API. Metrics are calculated from PostgreSQL state rather than inferred from transient queue contents.

POST /events requires an Idempotency-Key. The first request creates one event and one initial delivery. Repeating the same key with the same endpoint, event, and payload returns the existing records. Reusing the key for different input returns 409 idempotency_conflict.

PostgreSQL uniqueness makes concurrent identical requests converge. An in-memory lock would not provide the same database-backed guarantee.

Durable acceptance comes before queue scheduling. If Redis scheduling fails, the API returns 503 with durableAccepted: true, asking the client to retry the same request with the same idempotency key.

That boundary is part of the design, not a hidden promise of exactly-once execution. A receiver can process a request before a worker crashes while recording success; a later retry may deliver the same logical event again.

Retries follow a fixed 5s / 15s / 45s / 120s schedule, for a maximum of five attempts. A five-second request timeout bounds the network operation. Only failures classified as transient consume that retry budget.

Only dead-letter deliveries can be replayed. Replay has its own idempotency key and creates a new linked delivery with a fresh retry budget. The source is never reset: its terminal status and original attempt history stay intact.

Every request is authenticated with HMAC-SHA256 over timestamp.rawBody. The included receiver example validates timestamp freshness and compares signatures in constant time. Authentication and multi-tenancy for the platform itself remain outside the current version.

The committed local benchmark used one API process, one BullMQ worker, one PostgreSQL instance, one Redis instance, and an immediate local HTTP receiver.

Two correctness tests each issued 25 concurrent requests. Identical ingestion converged to one event and one initial delivery. Identical replay requests converged to one replay delivery, while the source dead letter remained unchanged.

The deterministic receiver also exercises immediate success, 500 → 500 → 200 recovery, and exhaustion after five failures through the real API, queue, worker, signing, and database paths.

Read the committed benchmark evidence ↗

The implemented local scope includes the API, durable data model, queue worker, request signing, bounded retries, dead-letter recovery, idempotent replay, dashboard, deterministic demo, tests, and benchmark evidence.

The next reliability extension would address the documented database / queue dual-write gap with an outbox or reconciliation mechanism. That is outside the current implementation and is not represented as shipped.

Other deliberate non-goals are platform authentication and multi-tenancy, secret encryption or rotation, horizontal worker-capacity validation, multi-region delivery, and high-availability guarantees. Keeping those boundaries visible makes the local evidence easier to interpret.