Webhook

Outbound event webhooks: subscription management, HMAC signing, delivery, and retries via BullMQ.

Overview

Property	Value
Directory	`apps/backend/webhook`
Port	`8013`
Local URL	`https://local.reloop.sh/api/webhook`
Swagger UI	`https://local.reloop.sh/api/webhook/openapi`
Stack	ElysiaJS · PostgreSQL · Redis · NATS · BullMQ

Quick start

bun be:webhook:dev

Or bun backend:dev / bun dev.

Environment

apps/backend/webhook/.env (from bun setup / bun env:setup).

PG_URL=postgresql://reloop:reloop123@localhost:5432/reloop
REDIS_URL=redis://:reloop123@localhost:6379
WEBHOOK_ENCRYPTION_KEY=your-64-char-hex-key
PORT=8013
BASE_URL="https://local.reloop.sh"
NATS_URL=nats://localhost:4222
NODE_ENV=development

WEBHOOK_ENCRYPTION_KEY encrypts stored webhook signing secrets. If unset, secrets are stored in plaintext (local only). The workflow service decrypts them to sign deliveries, so it needs the same value.

Variable	Required	Default
`PG_URL`	YES	`postgresql://...`
`REDIS_URL`	YES	`redis://...`
`WEBHOOK_ENCRYPTION_KEY`	Prod only	Dev key in `.env.dev`
`PORT`	YES	`8013`
`BASE_URL`	YES	`https://local.reloop.sh`
`NATS_URL`	YES	`nats://localhost:4222`

Commands

Command	Description
`bun be:webhook:dev`	Start dev server with hot reloading
`bun run --filter=be-webhook build`	Compile production bundle
`bun run --filter=be-webhook start`	Run compiled production build
`bun run --filter=be-webhook check-types`	TypeScript type-check

Architecture

Layer	Detail
Control plane	This service: CRUD endpoints, list deliveries, manual replay
Dispatcher	`be-workflow` NATS queue group `webhook-dispatcher` (email lifecycle + manual trigger)
Delivery	Dedicated BullMQ queue `webhook-delivery-queue`; signs with `Reloop-Signature`
Retries	Fixed 7-attempt schedule (5s → 5m → 30m → 2h → 5h → 10h)
Helpers	`@reloop/webhook-delivery` (envelope, HMAC, SSRF client)
Schema	`packages/db/src/schema/webhook.ts`

Setup

One-command local bootstrap

Port reference

Gateway routes and ports

Mail

Source of delivery events

Logs

Analytics event sink