Waybill

Docs

Clear documentation
for real-world use.

Get up and running with setup guides, API references and delivery behaviour from the current project.

View on GitHub
Search topic names and keywords. Press Enter to open the first result.

System

Configuration

Use .env.example as the configuration reference. The values below describe host-run Bun processes with the supplied local Docker services.

Process connections

VariablePurpose / local default
DATABASE_URLPrimary PostgreSQL on 127.0.0.1:15432/webhook_platform.
REDIS_URLredis://localhost:6379 for limits and circuits.
AWS_REGIONRegion containing your SQS queue and S3 bucket.
SQS_QUEUE_URLYour real queue URL; replace the example account placeholder.
S3_BUCKET_NAMEYour configured payload/archive bucket.
API_PORT3000 by default.
RECEIVER_URLOne destination for the worker; local default is http://127.0.0.1:4000/webhook.
RECEIVER_PORT4000 for the included test receiver.
RECEIVER_TENANT_ID / RECEIVER_HMAC_SECRETTrusted tenant and matching signing secret for the test receiver.

Configure AWS credentials server-side. Do not expose database URLs, AWS credentials or signing secrets through NEXT_PUBLIC_* variables.

Physical read replica

Set up the local replica
bun run setup:replica

The setup starts the optional PostgreSQL replica on port 15433 and creates a dedicated reader. Configure the host connection:

Local read-replica environment
READ_REPLICA_DATABASE_URL=postgresql://waybill_reader:local-reader-only@127.0.0.1:15433/webhook_platform

The helper verifies pg_is_in_recovery() inside a read-only transaction and rejects a primary. Container networking uses different hostnames from host-run Bun processes. A managed hosted replica remains deployment work.

Worker and rate defaults

VariableDefault
MAX_DELIVERY_ATTEMPTS8 attempts.
SQS_MAX_MESSAGE_BYTES262144 payload bytes before S3 claim-check.
INGESTION_RATE_LIMIT_CAPACITY / DELIVERY_RATE_LIMIT_CAPACITY10 tokens each.
INGESTION_RATE_LIMIT_REFILL_PER_SECOND / DELIVERY_RATE_LIMIT_REFILL_PER_SECOND10 tokens per second each.

The environment template also lists CIRCUIT_BREAKER_FAILURE_THRESHOLD and CIRCUIT_BREAKER_COOLDOWN_MS. The current worker does not read those variables: its circuit module uses defaults of 5 failures and 30000 ms.