hookem

Hookem is an SST-first webhook fanout demo stack for at-least-once delivery. It uses typed package boundaries, MiniStack-compatible local infrastructure, signed webhook delivery, durable attempt records, and an end-to-end smoke workflow that exercises the deployed path instead of manually invoking handlers.

Project Overview

The repository is organized as a pnpm/Moon monorepo:

• services/svc-webhook-api: registration lifecycle API and health endpoint.
• services/svc-webhook-receiver: Kinesis consumer that resolves registrations and enqueues delivery jobs.
• services/svc-webhook-sender: SQS consumer that sends webhooks, signs payloads, records attempts, and reports batch failures.
• packages/*: shared contracts, config, DB access, event/queue/http helpers, and telemetry helpers.
• infra: local bootstrap helpers.
• apps/web-status: browser status page for local visibility into the deployed stack.
• scripts/local: maintained local smoke workflow.
• docs: architecture, validation, observability, local development, and follow-up notes.

The deployed flow is:

1. Clients register webhook destinations through the API.
2. Events are published to Kinesis.
3. The receiver Lambda fans events out to matching registrations through SQS.
4. The sender Lambda delivers signed webhook payloads and persists each attempt to DynamoDB.
5. Smoke tests and the status page provide operational evidence that the system is behaving.

Core AWS resources are defined in sst.config.ts:

• API Gateway HTTP API
• Lambda functions for API, receiver, and sender
• Kinesis stream
• SQS queue
• DynamoDB registration and attempt tables
• S3-hosted status page assets for local MiniStack deployment

For deeper diagrams and flow details, see docs/architecture.md.

Observability

The repo includes multiple visibility paths:

• @hookem/telemetry spans, counters, and histograms.
• Structured JSON logs through correlationLog().
• Durable webhook attempt evidence in DynamoDB.
• MiniStack smoke output with registration, publish, receipt, signature, and attempt evidence.
• A local status page app that polls the deployed status page, API health endpoint, and MiniStack health endpoint.

Status page:

The status page is deployed with the stack and the local URL is emitted as WebStatusUrl in .sst/outputs.json.

Tooling

• Node version is defined by .nvmrc (24).
• Package manager: pnpm.
• Task runner: Moon pinned to 1.41.7.
• Package scope: @hookem/*.
• Workspace imports use package names/exports only.
• Lint/format uses Oxc (oxlint, oxfmt).
• Workflows are Moon tasks, not package.json scripts.

Local Runbook

1. Install dependencies

nvm install
nvm use
pnpm install

2. Start MiniStack

Run MiniStack in a dedicated terminal because the task stays attached:

pnpm exec moon run root:ministack-start

In another terminal, wait for MiniStack to report healthy:

pnpm exec moon run root:ministack-health

3. Deploy the entire stack locally

Load the committed demo-safe .env values and deploy through SST:

set -a; source .env; set +a; pnpm exec sst deploy --stage prod

After deploy, inspect outputs:

cat .sst/outputs.json

The outputs include:

• ApiUrl
• EventStreamName
• QueueUrl
• RegistrationsTableName
• AttemptsTableName
• WebStatusUrl

Open WebStatusUrl in a browser to view the local status page.

4. Run the local smoke test

Run the maintained end-to-end MiniStack smoke flow:

set -a; source .env; set +a; pnpm exec moon run root:ministack-ci-smoke

The smoke test validates the production-shaped workflow:

• creates success and failure registrations through the API boundary
• publishes an event to Kinesis
• waits for receiver and sender Lambda processing
• validates signed webhook receipt
• validates success and failure attempt records
• deregisters the smoke registrations during cleanup

Useful Checks

Run the full repo check:

pnpm exec moon run root:check

Run service entrypoint checks:

pnpm exec moon run svc-webhook-api:check
pnpm exec moon run svc-webhook-receiver:check
pnpm exec moon run svc-webhook-sender:check

Run status page checks:

pnpm exec moon run web-status:typecheck
pnpm exec moon run web-status:build

Run the status page locally with Vite:

pnpm exec moon run web-status:dev

Docs Index

• Architecture + Mermaid diagrams: docs/architecture.md
• Local development: docs/local-dev.md
• Local testing + smoke evidence: docs/local-testing.md
• Status page app: docs/status-page.md
• Demo validation notes: docs/demo-validation-notes.md
• System dependencies inventory: docs/system-dependencies.md
• Acceptance traceability matrix: docs/acceptance-traceability.md
• Follow-up improvement list: docs/todo-improvements.md
• Full implementation plan source: docs/issue-1-v1-plan.md