Docs/onboarding env webhooks

.env.example

@@ -1,15 +1,28 @@
-CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001
+# Server Configuration
+# PORT is optional; defaults to the application default when omitted.
+PORT=3001
+NODE_ENV=development
+
+# CORS Configuration
+# FRONTEND_URL is mandatory at startup.
 FRONTEND_URL=http://localhost:3000
+# Optional backward-compatible fallback for multiple allowed origins during migration.
+CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001
 
+# Database and Queue Infrastructure
+# DATABASE_URL and REDIS_URL are mandatory at startup.
 DATABASE_URL=postgres://postgres:postgres@db:5432/remitlend
 REDIS_URL=redis://redis:6379
 
 # Stellar Configuration
-# Select network defaults ("testnet" or "mainnet")
+# STELLAR_RPC_URL, STELLAR_NETWORK_PASSPHRASE, LOAN_MANAGER_CONTRACT_ID,
+# LENDING_POOL_CONTRACT_ID, POOL_TOKEN_ADDRESS, and LOAN_MANAGER_ADMIN_SECRET
+# are mandatory at startup.
+# Select network defaults ("testnet" or "mainnet").
 STELLAR_NETWORK=testnet
-# Optional override (defaults from STELLAR_NETWORK; must match selected network)
+# Optional override (defaults from STELLAR_NETWORK; must match selected network).
 STELLAR_RPC_URL=https://soroban-testnet.stellar.org
-# Optional override (must match selected network exactly)
+# Optional override (must match selected network exactly).
 STELLAR_NETWORK_PASSPHRASE=Test SDF Network ; September 2015
 LOAN_MANAGER_CONTRACT_ID=
 REMITTANCE_NFT_CONTRACT_ID=
@@ -19,18 +32,22 @@ POOL_TOKEN_ADDRESS=
 STELLAR_USDC_ISSUER=
 STELLAR_EURC_ISSUER=
 STELLAR_PHP_ISSUER=
-# Secret key for the on-chain LoanManager admin account (G... / S...)
+# Secret key for the on-chain LoanManager admin account (G... / S...).
 LOAN_MANAGER_ADMIN_SECRET=
-# Optional override for score reconciliation read calls
+# Optional override for score reconciliation read calls.
 SCORE_RECONCILIATION_SOURCE_SECRET=
 
-# Loan configuration (required)
+# Loan Configuration
 LOAN_MIN_SCORE=500
 LOAN_MAX_AMOUNT=50000
 LOAN_INTEREST_RATE_PERCENT=12
 CREDIT_SCORE_THRESHOLD=600
+# Must match the deployed contract if it ever changes from the repo default.
+LOAN_TERM_LEDGERS=17280
 
-# Score Deltas (used by indexer to update user scores)
+# Score Deltas
+# SCORE_DELTA_REPAY, SCORE_DELTA_DEFAULT, and SCORE_DELTA_LATE are mandatory
+# at startup and are used by the indexer to update user scores.
 SCORE_DELTA_REPAY=15
 SCORE_DELTA_DEFAULT=50
 SCORE_DELTA_LATE=5
@@ -40,40 +57,42 @@ INDEXER_POLL_INTERVAL_MS=30000
 INDEXER_BATCH_SIZE=100
 
 # Default checker (on-chain `check_defaults`)
-# How often to scan + submit default checks while the API process is running
+# How often to scan + submit default checks while the API process is running.
 DEFAULT_CHECK_INTERVAL_MS=1800000
-# Max loans to include per scheduled run (safety valve)
+# Max loans to include per scheduled run (safety valve).
 DEFAULT_CHECK_MAX_LOANS_PER_RUN=500
-# Number of loan IDs per Soroban transaction
+# Number of loan IDs per Soroban transaction.
 DEFAULT_CHECK_BATCH_SIZE=25
-# Max time to wait for a single batch submission before moving on
+# Max time to wait for a single batch submission before moving on.
 DEFAULT_CHECK_BATCH_TIMEOUT_MS=300000
-# Number of concurrent batches to submit
+# Number of concurrent batches to submit.
 DEFAULT_CHECK_CONCURRENCY=3
-# Polling configuration after submission
+# Polling configuration after submission.
 DEFAULT_CHECK_POLL_ATTEMPTS=30
 DEFAULT_CHECK_POLL_SLEEP_MS=1000
-# Must match the deployed contract if it ever changes from the repo default
-LOAN_TERM_LEDGERS=17280
 
-# Score reconciliation
+# Score Reconciliation
 SCORE_RECONCILIATION_INTERVAL_MS=3600000
 SCORE_RECONCILIATION_MAX_BORROWERS_PER_RUN=500
 SCORE_RECONCILIATION_BATCH_SIZE=25
 SCORE_RECONCILIATION_AUTOCORRECT_ENABLED=false
 SCORE_RECONCILIATION_AUTOCORRECT_THRESHOLD=50
 
 # Authentication
+# JWT_SECRET and INTERNAL_API_KEY are mandatory at startup.
 JWT_SECRET=your-super-secret-jwt-key-change-in-production
 INTERNAL_API_KEY=change-me
 
 # Webhooks
+# Per-subscription webhook signing secrets are stored when a webhook subscription
+# is registered. WEBHOOK_REQUEST_TIMEOUT_MS and WEBHOOK_MAX_PAYLOAD_BYTES are optional.
 WEBHOOK_REQUEST_TIMEOUT_MS=30000
+WEBHOOK_MAX_PAYLOAD_BYTES=65536
 
 # Sentry (leave blank to disable; set SENTRY_DSN in staging/production)
 SENTRY_DSN=
 
-# Notifications
+# Notifications and Cleanup Jobs
 NOTIFICATION_RETENTION_DAYS=90
 READ_NOTIFICATION_RETENTION_DAYS=30
 
@@ -89,6 +108,3 @@ ADMIN_WEBHOOK_URL=
 TWILIO_ACCOUNT_SID=
 TWILIO_AUTH_TOKEN=
 TWILIO_PHONE_NUMBER=
-
-# Redis Configuration (Local)
-REDIS_URL=redis://localhost:6379