Integrating with SNOW

Generic guide for any application sending summarization work to SNOW. Tenant-specific operational details (your key prefix, daily quota, webhook URL on file) live in your own tenant page in the SNOW portal.

For full request/response shapes, see:

• docs/contract/v1.md — endpoints, auth, idempotency, quotas, rate limits
• docs/webhooks/v1.md — webhook signing, retries, replay

Pick an endpoint

Need	Endpoint	Mode
Summarize a clinical event you describe in JSON	POST /v1/sessions	async, webhooks
Patient fills a form, you want a brief back	POST /v1/intake-sessions (token issued, patient submits)	async, webhooks
Single-shot intake summary, no patient hand-off	POST /v1/intake	sync, response inline

Async endpoints return 201 with an id and emit webhooks as work progresses. Sync endpoints return the summary inline and emit no webhooks.

Webhook events

Every async resource emits the same lifecycle:

<resource>.created       work accepted into queue
<resource>.processing    pipeline started
<resource>.completed     summary ready (data.summary populated)
<resource>.failed        unrecoverable error (data.error populated)

Current resources: session, intake_session, document. Plus session.test for portal-triggered tests.

A handler that ignores resources it doesn’t care about scales to future resources without code changes:

const [resource, verb] = event.split(".")
if (resource !== "session" && resource !== "intake_session") return ack()
// route on verb

Idempotency

Send Idempotency-Key on every POST. The first response (2xx or 4xx) is cached for 24h; retries with the same key return the original response with X-Idempotent-Replay: true and do not consume quota or credits.

Use a deterministic key tied to your own logical event (appointment id, form id, trigger id) — not a random UUID — so retries collapse but distinct events don’t.

5xx responses are not cached. Retries on those will re-run.

Quota

Authenticated POSTs are subject to a per-tenant daily count (UTC midnight reset) and a per-minute rate limit. Both expose headers; the daily cap returns 429 with Retry-After. See contract/v1.md §7. Sandbox keys (sn_test_*) bypass both.

Webhook delivery contract

• HMAC-SHA256 over ${t}.${rawBody}, sent in X-Snow-Signature: t=…,v1=…
• Replay window 300s
• Retries: 10s → 60s → 5m → 30m, then dead-letter
• 24h secret-rotation grace window with dual signatures

Your handler must verify the signature, dedupe on X-Snow-Delivery, and return any 2xx within 10s. See webhooks/v1.md for the verifier.