Two planes of real-time
Real-time integration runs on two planes. The streaming backbone is a Kafka-compatible event substrate that carries platform and venture events between services — the durable, ordered, replayable plane. The push plane delivers signed HTTP webhooks to endpoints ventures and integrators operate, and realtime channels to connected clients. Both planes carry the same rule: consumers receive events; they never poll the record of another brand.
The transactional outbox
Every event begins as a database fact. When state changes, the event announcing it is written in the same transaction as the change itself — an event can never claim a change that did not commit, and a committed change can never lose its announcement. A background publisher then drains the outbox:
- At-least-once delivery. The platform retries until the consumer acknowledges; delivery is a guarantee, and idempotency at the consumer is the contract's other half — design handlers so a duplicate delivery is a no-op.
- Ordered within a partition. Events partition by brand context, so a brand's stream arrives in order. Cross-brand ordering is explicitly not promised.
- Retries with backoff, then dead letters. Failing deliveries retry with exponential backoff up to an attempt ceiling, then land in a dead-letter queue where operators can inspect and replay them. A replay service exists for recovery — nothing is silently dropped.
Validated event contracts
Event types are registered contracts, validated twice: before emit (the producer cannot publish a malformed event) and again on receive (the consumer never processes one). Event evolution follows the same additive-change rule as the HTTP contracts — see API versioning & compatibility. A consumer written against an event contract will not have the type changed underneath it.
Signed webhooks, verified correctly
Outbound webhooks are signed so receivers can prove origin and freshness:
X-MCV-Signature: t=1721725200000, v1=9f86d081884c7d65…
# v1 = HMAC-SHA256(signing_secret, "<t>.<raw request body>")Verification has four rules, and each exists because skipping it is a known breach pattern:
- Verify over the raw body bytes — never a re-serialized payload, which can differ in whitespace or key order and silently break (or bypass) the check.
- Check the timestamp. It participates in the signature, and receivers reject messages outside a short replay window (five minutes by default; tighten to one if your endpoint can).
- Compare in constant time. Signature comparison uses a timing-safe equality check.
- Fail quietly outward, loudly inward. A failed verification returns a generic refusal; the reason is logged on your side, never explained to the sender.
Platform ↔ venture traffic
Platform-to-venture updates (profile changes, status changes) arrive as signed sync webhooks on the push plane. Venture-to-platform telemetry — the audit events every venture owes — streams onto the substrate on per-venture topics, as venture onboarding describes. Both directions run through the same outbox machinery — durable, retried, and replayable under operator control.
Boundary
This page describes the integration model. Topic names, endpoint configuration, signing secrets, and retention settings ship with authenticated developer access.