Sandwich Pipe

What it is

Sandwich Pipe is the private-link layer between care-data producers and Sandwich's family-facing app. Think of it as Plaid for caregiving: agencies, EHRs, and home-health platforms push structured events at Sandwich Pipe, and Sandwich lights up the right loved-one record for the right family in real time.

Why a pipe

• Neutral shape. One event schema — institution_id, subject_ref, event_type, payload — lets us onboard any partner without redesigning the app.
• Signed and replayable. Every request carries X-SandwichPipe-Signature: sha256=…, computed over the raw body with a per-partner secret. Replays are cheap; forgeries are not.
• Fire-and-forget on the partner side. Partners never block their own workflow waiting on Sandwich. If Sandwich Pipe is down, events are queued and retried with exponential backoff.
• Family-controlled visibility. Events flow only when the loved one's family-share is on. Partners don't need to know who can see what — Sandwich enforces it on the receiving side.

Which providers fit this lane?

Sandwich Pipe is a push-style webhook ingest. It’s the right lane for any provider that can sign and POST events when something happens on their side. It’s not the right lane for portals that families log into themselves — those need a different shape (see below). Three lanes, by category:

Quick test: does the provider make data available by sending it to you when it changes, or only by letting the family log in to view it? If they push, the Pipe is the right lane. If they only let the family log in, that’s patient-portal pull (FHIR roadmap). If they only send email, that’s the Family Inbox.

Event envelope

{
  "institution_id": "sandwichsoft-sunrise-home-care",
  "subject_ref":    "client_8c1f",
  "event_type":     "visit_ended",
  "occurred_at":    "2026-04-16T21:04:00Z",
  "payload": {
    "caregiver_id":      "caregiver_maria_r",
    "actual_end":        "2026-04-16T21:04:00Z",
    "duration_minutes":  92
  }
}

Field reference:

Signing requests

Compute HMAC-SHA256(raw_body, partner_secret) and send the hex digest prefixed with sha256=. Sandwich verifies in constant time and rejects anything older than 5 minutes (clock-skew tolerant).

POST /sandwichpipe/v1/events HTTP/1.1
Host: api.joinsandwich.com
Content-Type: application/json
X-SandwichPipe-Institution: sandwichsoft-sunrise-home-care
X-SandwichPipe-Signature: sha256=4f8a9b2e…
X-SandwichPipe-Timestamp: 2026-04-16T21:04:01Z

const sig = "sha256=" + hmacSha256Hex(secret, rawBody);
headers["X-SandwichPipe-Signature"]   = sig;
headers["X-SandwichPipe-Institution"] = institutionId;
headers["X-SandwichPipe-Timestamp"]   = new Date().toISOString();

Per-partner secrets are issued at onboarding and rotated quarterly. A second secret window is provided during rotation so you can roll keys without dropped events.

Event types (v1)

Future event types will be added without breaking changes. Partners should send unknown types as new ones become available; Sandwich will accept and forward to families based on family-share configuration.

Family share

For outside partners, family-share is established by the agency that owns the client relationship. Sandwich will not display events to a family unless the agency has affirmatively opted that client in. This keeps the partner's compliance posture clean — you forward events to Sandwich Pipe, and Sandwich enforces the family-side authorization.

What it can & can’t do

Sandwich Pipe handles:

• Signed, partner-pushed events about clients whose family-share is on.
• Five core event types — visit start/end, observations, medications administered, vitals recorded — with room for partner-specific extensions in the payload.
• Idempotency — duplicate events with the same partner-side identifier are de-duplicated before they reach the family timeline.
• Replay-safe retries with exponential backoff if Sandwich Pipe is briefly unavailable.

Sandwich Pipe does not:

• Pull data on its own. If a partner doesn’t POST it, it doesn’t exist. There is no scraper, no polling, no portal-login impersonation.
• Authenticate end-users. Partners authenticate themselves with a per-partner secret. The family side is authenticated separately by Sandwich.
• Bridge MyChart, Epic, or other patient portals. Those are read-by-portal-login, not push, and need a different connector pattern (FHIR — on the roadmap).
• Replace clinical systems. Sandwich is the family-visible layer. Partners’ own clinical systems remain the source of truth.
• Cross caregivers. Family-share is opt-in per client. An agency turning off family-share stops the data flow immediately.

Errors & retries

Sandwich Pipe responds with one of these statuses. Partners should treat 5xx as retriable with exponential backoff and 4xx as terminal (fix the request and resend, but don't retry the original).

Becoming a partner

Sandwich Soft agencies get Sandwich Pipe for free — it's wired into clock-in and clock-out. Outside partners (EHRs, hospital discharge systems, other agency platforms) can email hello@joinsandwich.com to start the onboarding conversation.

What you'll need:

• A signed Business Associate Agreement (BAA) — Sandwich will provide a template.
• A list of institution_id namespaces you want issued (one per tenant on your platform if you're multi-tenant).
• A short security review on your end — we'll run one too — confirming the receiving system handles redacted PHI per HIPAA.

Sandbox secrets are typically issued within a week of the security review.

Looking for the rest of the stack? MCP · Sandwich Soft · All docs