Ingest
Ingest
Section titled “Ingest”Ingest is how source-system events enter Atlas. A delivery lands on one canonical event envelope, is recorded, and is mapped + reconciled onto the canonical model asynchronously on a worker.
Endpoints are per source
Section titled “Endpoints are per source”Each source system maps to its own ingest endpoint id and HMAC secret. A workflow picks which source it is feeding by addressing that endpoint — the multi-MIS handle a single shared connector never had.
POST /v1/ingest/{endpoint_id}Authentication: endpoint HMAC, not JWT
Section titled “Authentication: endpoint HMAC, not JWT”Ingest is authenticated by the endpoint’s HMAC secret, not the per-tenant JWT. The caller signs the raw JSON body and sends the signature header:
X-Synergy-Signature: sha256=<hex hmac of the raw body>This lets external systems POST directly to an endpoint without holding a tenant JWT, while the signature proves the delivery is authentic for that endpoint.
Idempotent replay
Section titled “Idempotent replay”Ingest is idempotent. The response distinguishes a first delivery from a replay:
// 202 Accepted (recorded) — or 200 OK (idempotent duplicate){ "envelope_id": "env_…", "duplicate": false }202+duplicate: false— recorded for the first time.200+duplicate: true— the same delivery was already recorded; the replay is a no-op. The same event never double-applies.
Reconciliation
Section titled “Reconciliation”After an envelope is recorded, a worker maps it onto the canonical model and reconciles it with any existing record — minting a canonical id on first sight, updating cross-references, recording per-field provenance, and surfacing drift when two sources disagree. Reconciliation is decoupled from the request, so a burst of deliveries never blocks the caller.
Delivering via the stack
Section titled “Delivering via the stack”In a stack workflow, the atlas.ingest node delivers an envelope (it signs the
body for you). See Integration.