Getting started

1. Prepare the checkout#

You need Bun, Docker Compose, an SQS queue, an S3 bucket and AWS credentials with the required access. From the repository root:

bun install
cp .env.example .env

Edit .env before starting the services. Set DATABASE_URL, REDIS_URL, AWS_REGION, AWS credentials, SQS_QUEUE_URL and S3_BUCKET_NAME. Values in .env.example are local defaults or placeholders.

2. Initialize local data#

docker compose up -d postgres redis
bunx prisma@5.22.0 migrate deploy --schema packages/shared/prisma/schema.prisma
bun run prisma:generate
bun run seed:tenant

PostgreSQL is exposed on port 15432 and Redis on 6379. The seed command creates dev-tenant if absent and prints its UUID. It does not reset an existing tenant or print its signing secret.

3. Configure the receiver#

Read the seeded tenant’s ID and signing secret locally:

docker compose exec -T postgres psql -U webhook -d webhook_platform \
  -c "SELECT id, hmac_secret FROM tenants WHERE name = 'dev-tenant';"

Set these server-side values in .env, using that record’s values:

RECEIVER_URL=http://127.0.0.1:4000/webhook
RECEIVER_TENANT_ID=REPLACE_WITH_TENANT_UUID
RECEIVER_HMAC_SECRET=REPLACE_WITH_THAT_TENANTS_SECRET

The test receiver accepts one configured tenant and verifies its signature. Signing secrets belong in the server environment, never in public frontend variables.

4. Start the processes#

Run each command in a separate terminal from the repository root:

curl --max-time 10 http://127.0.0.1:3000/health

The health endpoint returns { "status": "ok" }. Send an event using the request examples. bun run post:event also submits an event for the seeded development tenant.

5. Enable delivery reads#

History and dead-letter reads require a physical replica. Follow read-replica setup before using those endpoints. To run the public frontend, use bun run dev:web; its local port is 3001.