Atlas Core

Webhook Ingress (local)

• Endpoint: POST http://localhost:3000/webhook
• Auth: require x-atlas-webhook-secret: <secret>; this is the only accepted auth header (Authorization is ignored).
• Secret: set ATLAS_WEBHOOK_SECRET in all non-local environments. If unset and NODE_ENV is not production, the expected secret defaults to atlas-dev-secret (dev only). In production with a missing secret, all requests will 401.
• Response codes: 202 means the payload was validated and accepted into processing (queued/handed to the core); downstream work may still be async and may fail later (e.g., rules/timers). 401 means missing/wrong secret.
• Payload schema: must match AtlasEventSchema (eventId, eventType, occurredAt ISO string, source, propertyId, unitId, issueId, payload). All fields are required; payload defaults to {} if omitted.
• Enums (case-sensitive): eventType one of IssueCreated, IssueUpdated, IssueClassified, IssueClosed, VendorDispatched, VendorAccepted, VendorDeclined, VendorArrived, VendorNoResponseDetected, JobCompleted, SLATimerStarted, SLATimerBreached, ProofMissingDetected, RuleConflictDetected, EscalationTriggered. source one of PMS, Atlas, VendorPortal, Simulator.
• Optional debug logging: set DEBUG_WEBHOOK=true to log accepted webhook event metadata.
• Optional simulator feed in hybrid runner: set RUN_SIMULATOR=true to also replay the sample events; otherwise hybrid waits for webhooks only.

Example (uses default dev secret):

curl -X POST http://localhost:3000/webhook \
  -H "x-atlas-webhook-secret: atlas-dev-secret" \
  -H "Content-Type: application/json" \
  -d '{"eventId":"demo1","eventType":"IssueCreated","occurredAt":"2024-01-01T00:00:00.000Z","source":"Simulator","propertyId":"TEST","unitId":"1-01","issueId":"ISSUE-1","payload":{"category":"GENERAL","priority":"STANDARD","afterHours":false,"occupied":true}}'

Runner commands

• Webhook-only hybrid (no simulator): DEBUG_WEBHOOK=true npm run atlas:hybrid
• Simulator + webhook hybrid: DEBUG_WEBHOOK=true RUN_SIMULATOR=true npm run atlas:hybrid

You can omit DEBUG_WEBHOOK if you don't want ingress debug logs. The hybrid runner still polls the provider; with RUN_SIMULATOR=true it also seeds the sample events before polling.

Testing

• Run tests with coverage: npm test (Vitest, with coverage thresholds configured).

CI

• Tests run on every push and pull request via GitHub Actions.
• Local check: npm test.