Configuration

A scaffolded Hogsend app is configured entirely through environment variables. Both the HTTP API (src/index.ts) and the worker (src/worker.ts) read from the same .env at your app's root. The engine validates them at startup with @t3-oss/env-core — a missing or malformed required variable fails the boot with a clear error.

cp .env.example .env

pnpm bootstrap does this for you and more: it copies .env.example, generates a real BETTER_AUTH_SECRET, auto-mints your HATCHET_CLIENT_TOKEN, runs the migrations, and mints an ingest-scoped HOGSEND_API_KEY data-plane key — see Installation. The .env.example shipped by the scaffold already points DATABASE_URL and REDIS_URL at the local Docker Compose ports, so for local development you mostly just fill in RESEND_API_KEY when you're ready to send real email.

Variable reference

The Process column notes which process actually uses each value. They share one .env; set everything in both deployed processes.

Core

Authentication

Hogsend uses Better Auth for session management and admin authentication.

Email provider

Hogsend sends email through a swappable provider — Resend by default. The provider is a dumb EmailProvider; the engine owns render → preferences → tracking → email_sends, so swapping providers never costs you those features. Postmark ships as an installable opt-in, and any other provider works behind the EmailProvider contract.

The active provider resolves as email.defaultProvider (passed to createHogsendClient) → EMAIL_PROVIDER → "resend". Registering a provider never activates it; you flip the active id with EMAIL_PROVIDER. An unregistered active id throws at boot (it never silently falls back for a non-Resend id).

Resend (default)

Postmark (opt-in)

Postmark ships as @hogsend/plugin-postmark (install with pnpm add @hogsend/plugin-postmark@latest). Setting the server token only builds the preset — it never changes the active provider on its own; activate it with EMAIL_PROVIDER=postmark. Postmark has no HMAC: webhook authenticity is HTTP Basic credentials in the URL, and verifyWebhook fails closed when they're unset.

Provider delivery events arrive at POST /v1/webhooks/email/:providerId (e.g. /v1/webhooks/email/postmark) and are normalized to a provider-neutral EmailEvent. POST /v1/webhooks/resend is kept as a thin deprecated alias. See Email for the full provider-swap walkthrough and the defineEmailProvider contract.

Hatchet

Hatchet handles durable task execution — journey orchestration, email sends, and background jobs. These three values are the whole connection.

Data plane

The public data plane (/v1/contacts, /v1/events, /v1/emails, /v1/lists, /v1/campaigns) is how your own product code writes into Hogsend via @hogsend/client and the hogsend CLI. Every call needs a Bearer API key carrying the ingest scope.

PostHog

Optional — connects to your PostHog instance for event ingestion and person property fetching.

Integration presets

Hogsend ships built-in inbound webhook sources for Clerk, Supabase, Stripe, and Segment, served at POST /v1/webhooks/{id}. Setting a preset's signing secret auto-enables that source — no code change. A signature-verified preset fails closed: if its secret is unset, the source is never mounted; a request with a bad signature is rejected with 401. See Integrations for the per-provider event mappings.

Outbound webhooks

Hogsend emits a signed event stream to your subscriber URLs and delivers it with a durable, at-least-once retry task. Endpoints are managed through the admin API — these variables only tune the delivery engine. All are optional; the durable task carries the listed defaults. See Outbound webhooks for the event catalog and signing scheme.

Outbound destinations

A destination is a delivery-time transform keyed by webhook_endpoints.kind that fans the outbound event stream out to a product or data tool (PostHog, Segment, Slack, a CRM, a warehouse), reusing the same durable delivery as outbound webhooks. Credentials are not env vars — they live per-endpoint in webhook_endpoints.config, managed via the admin API / hs.webhooks SDK.

Features

These mirror the *-or-CSV contract: * registers everything, or pass a comma-separated list of ids. Anything not listed is not registered. Each can also be passed explicitly to createHogsendClient({ ... }) / createWorker({ ... }).

Infrastructure

The local docker-compose.yml host ports are parameterized and default to 5434 (Postgres), 6380 (Redis), and 8888/7077 (Hatchet dashboard/gRPC). pnpm bootstrap auto-remaps any that are already in use — writing the chosen POSTGRES_PORT / REDIS_PORT / HATCHET_DASHBOARD_PORT / HATCHET_GRPC_PORT into a root .env (for Compose) and syncing the matching DATABASE_URL / REDIS_URL / HATCHET_CLIENT_HOST_PORT — so several stacks can run side by side. You rarely set these by hand.

Schema & boot

Generating secrets

# BETTER_AUTH_SECRET (>= 32 chars) and ADMIN_API_KEY
openssl rand -hex 32

# POSTHOG_WEBHOOK_SECRET
openssl rand -hex 16

The ingest-scoped HOGSEND_API_KEY is minted by pnpm bootstrap locally; in production mint one with POST /v1/admin/api-keys and scopes ["ingest"] (see Authentication) — it is shown once.

Migrations — two tracks

A scaffolded app has two independent migration streams against the same database. A single pnpm db:migrate runs both, engine first:

• Your own tables live in src/schema/index.ts.
• pnpm db:generate generates a client-track migration from your src/schema changes.
• pnpm db:migrate runs scripts/migrate.ts: migrateEngine() then migrateClient() (it skips an empty client track). Both tracks serialize behind the same Postgres advisory lock.
• The boot guard in src/index.ts gates on the engine track only. A pending client migration surfaces as status: "migration_pending" on /v1/health for you to resolve — it never takes the API down.

The engine version pin

The scaffold pins every @hogsend/* package to a single version line in package.json (substituted from ENGINE_VERSION at scaffold time). Keep them in lockstep — the API, worker, and engine migrations all ship together. Upgrade within a major with:

pnpm up "@hogsend/*"     # bump engine + db + core + email + plugins together
pnpm db:migrate          # apply any new engine migrations

Then verify /v1/health shows both tracks inSync: true. This is the upgrade path — never a git merge. See Upgrading & Customizing.

Validating configuration

curl http://localhost:3002/v1/health

If the API fails to start, check its logs for @t3-oss/env-core validation errors indicating which variable is missing or malformed.

Environment-specific recommendations

Local development

NODE_ENV=development
PORT=3002
LOG_LEVEL=debug
DATABASE_URL=postgresql://growthhog:growthhog@localhost:5434/growthhog
REDIS_URL=redis://localhost:6380
HATCHET_CLIENT_HOST_PORT=localhost:7077
HATCHET_CLIENT_TLS_STRATEGY=none

pnpm bootstrap writes a working version of all of these (plus BETTER_AUTH_SECRET, HATCHET_CLIENT_TOKEN, and HOGSEND_API_KEY) into .env for you.

Production

NODE_ENV=production
LOG_LEVEL=info
API_PUBLIC_URL=https://api.yourdomain.com
BETTER_AUTH_URL=https://api.yourdomain.com
RESEND_FROM_EMAIL=noreply@yourdomain.com   # or EMAIL_FROM; "Name <addr>" works too
STUDIO_ADMIN_EMAIL=you@yourdomain.com       # bootstraps the first Studio admin on a fresh DB
ENABLED_JOURNEYS=*

On Railway, DATABASE_URL, REDIS_URL, and PORT are auto-wired by linking the Postgres and Redis services. See Deployment.

Next steps