Event stream

Thrive AI Health publishes asynchronous events (lab results, daily device data, coaching nudges) to partner-configured message queues. This page covers the delivery model, signature verification, and event catalog.

Delivery guarantees

Delivery model: at-least-once. Partners must be prepared to receive duplicates.
Acknowledgment timeout: 10 seconds from receipt at the queue.
Any 4xx, 5xx, timeout, or connection failure is treated as a failed delivery.

Retry policy

Retry schedule after a failed delivery: 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours, 24 hours.
Maximum retry window: 48 hours.
After the final attempt, the event is marked failed and surfaced to Thrive AI Health operations; partners are notified through their support channel.

Event idempotency

Every event carries a globally unique event_id.
Receivers must de-duplicate on event_id: Thrive AI Health will re-deliver the same event_id on retry.

Signature verification

Every event is wrapped in a signed envelope so partners can reject forged or replayed payloads.

HMAC signing demonstrates two things:

Authenticity: the event was produced by Thrive AI Health.
Integrity: the signed_at and body values have not been altered between production and receipt.

HMAC is not encryption. The event body is plaintext JSON; anything with read access to your queue can see its contents. Confidentiality is provided separately:

In transit: TLS is enforced by every supported queue service on every API call; nothing to configure.
At rest in the queue: managed by the partner's queue service; all three supported queue types encrypt at rest by default (AWS SQS supports SSE-SQS and SSE-KMS; Azure Event Hubs and Azure Storage Queue encrypt by default).
End-to-end payload encryption: not in v1. If a deployment requires bodies to be encrypted with a partner-supplied public key, contact your Thrive AI Health onboarding representative.

Envelope structure

Thrive AI Health wraps every event in a JSON envelope carrying the signature inline:

{
  "event_id": "evt_01J7V3XK9ZQ2F6AB0H9DDCM32K",
  "event_type": "daily.data.heart_rate.created",
  "signed_at": 1712345678,
  "signature": "3f7b8a2e1c6d9f0a4b5e7c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f",
  "body": "{\"event_id\":\"evt_01J7V3XK9ZQ2F6AB0H9DDCM32K\",\"event_type\":\"daily.data.heart_rate.created\",\"user_id\":\"123e4567-e89b-12d3-a456-426614174000\",\"timestamp\":\"2026-03-16T08:00:00Z\",\"value\":72,\"unit\":\"bpm\",\"provider\":\"apple_health_kit\",\"source_device\":\"Apple Watch\",\"raw_data\":{}}"
}

event_id: UUID matching the event_id inside body. Use for deduplication without parsing body.
event_type: duplicated from body so partners can route to the right handler without parsing.
signed_at: Unix epoch seconds at which Thrive AI Health signed and dispatched the message.
signature: hex-encoded HMAC-SHA256 of the string "{signed_at}.{body}" using the tenant's signing secret.
body: a JSON string (not a nested object) containing the full event payload.

Verification steps (in order)

Parse the envelope JSON.
Reject if signed_at is more than 5 minutes older than current server time (replay protection).
Recompute HMAC-SHA256(secret, signed_at + "." + body) and compare to signature using a constant-time comparator.
Only after steps 2–3 pass, JSON.parse(body) to access the event fields.

If any step fails, do not acknowledge the message; Thrive AI Health will re-deliver per the retry policy above.

Event catalog

v1 supports delivery to AWS SQS, Azure Event Hubs, and Azure Storage Queue targets. Register a queue via POST /v1/admin/org/queues/{queue_name}.

Event type	Category
`daily.data.heart_rate.created`	Vital events
`daily.data.blood_pressure.created`	Vital events
`daily.data.blood_oxygen.created`	Vital events
`daily.data.glucose.created`	Vital events
`daily.data.hrv.created`	Vital events
`daily.data.steps.created`	Activity events
`daily.data.calories_active.created`	Activity events
`daily.data.distance.created`	Activity events
`daily.data.weight.created`	Body events
`daily.data.fat.created`	Body events
`daily.data.sleep.created`	Sleep summaries
`daily.data.workout.created`	Workout summaries
`daily.data.stress_level.created`	Wellness events
`coach.nudge.created`	Coaching nudge cards and health actions

Detailed payload schemas for each event type are documented alongside the matching REST endpoint (e.g. sleep events share the shape of GET /v1/users/{user_id}/metrics/sleep/summary).

Supported queue types

`type`	Backing service	Auth model
`aws_sqs`	Amazon SQS	Cross-account IAM role (partner supplies `role_arn`) or resource policy granting `sqs:SendMessage` to the TAIH publishing principal returned in the response.
`azure_event_hubs`	Azure Event Hubs	Shared Access Signature token with Send permission on the target event hub (partner-issued).
`azure_storage_queue`	Azure Storage queue	Shared Access Signature token with Add permission on the target queue (partner-issued).

Secrets (SAS tokens) are write-only; the value is stored encrypted at rest and never echoed back in GET responses.

On this page