Truemed Session Review Complete Webhook

Truemed calls your endpoint once per session, when clinical review finishes. Read the session again to see how it resolved: qualification_status is approved when a clinician approved the qualified items, or rejected when a clinician declined the request or an initially-eligible item failed review.

In both cases you capture the hold for the qualified amount and release the rest. The per-item eligible, pre-approved, and ineligible split on the session’s order_items tells you how much qualifies. On approved, the qualified amount is eligible_amount_cents + preapproved_amount_cents. On rejected, the LMN-dependent eligible portion is zeroed, so you capture only any preapproved_amount_cents (pre-approved items never needed the LMN) and release the rest, collecting the balance on a regular card as an ordinary, non-HSA/FSA order.

A fully HSA/FSA-ineligible cart reads rejected from creation on every session read. There is nothing to review, so no event fires for it. To receive deliveries, subscribe to the truemed_session.truemed_review_complete event type. Channels that aren’t subscribed get nothing.

Example delivery

1 {
2   "webhook_delivery_id": "dlv_f3a91c0b7d2e485fa6b19c04d7e2513a",
3   "event_type": "truemed_session.truemed_review_complete",
4   "occurred_at": "2026-07-01T18:45:00Z",
5   "data": {
6     "truemed_session_id": "ts_01JZ7D4M3A8B9C0D1E2F3G4H5J",
7     "user_id": "shopify_customer_7001",
8     "qualification_status": "approved",
9     "is_testing": false,
10     "created_at": "2026-07-01T18:30:00Z"
11   },
12   "metadata": "{\"order_ref\":\"1001\"}"
13 }

Authentication: Requests are HMAC-SHA256 signed. The x-truemed-signature header carries a timestamp and the signature in the form t=<unix-timestamp>,v0=<hex-signature>. To verify: take the t value from the header, compute HMAC-SHA256 over <t>.<raw-request-body> with your webhook signing secret, and compare the hex digest to the v0 value. Sign the raw body bytes exactly as received, since re-serializing the JSON changes the bytes and breaks the signature.

Request Notes

The payload is a signed envelope:

webhook_delivery_id - Deterministic delivery id. Retries of the same delivery repeat the same value, so use it to deduplicate.
event_type - Which event this is, one of truemed_session.pending_authorization or truemed_session.truemed_review_complete.
occurred_at - ISO-8601 timestamp of when the event occurred.
data - A compact session summary: the session id, user id, qualification status at event time, and session metadata needed for correlation. Read the session for the full qualification and cart picture.
metadata: (Optional) - JSON-encoded string echoing whatever metadata the merchant supplied at session creation. Omitted if none was supplied.

Response Notes

Success Case

HTTP Status: 204

You do not need to include any content in the body.

Failure Case

Truemed will retry the requests to your backend with backoff for up to 7 days

Truemed calls your endpoint once per session, when clinical review finishes. Read the session again to see how it resolved: `qualification_status` is `approved` when a clinician approved the qualified items, or `rejected` when a clinician declined the request or an initially-eligible item failed review. In both cases you capture the hold for the qualified amount and release the rest. The per-item eligible, pre-approved, and ineligible split on the session's `order_items` tells you how much qualifies. On `approved`, the qualified amount is `eligible_amount_cents` + `preapproved_amount_cents`. On `rejected`, the LMN-dependent eligible portion is zeroed, so you capture only any `preapproved_amount_cents` (pre-approved items never needed the LMN) and release the rest, collecting the balance on a regular card as an ordinary, non-HSA/FSA order. A fully HSA/FSA-ineligible cart reads `rejected` from creation on every session read. There is nothing to review, so no event fires for it. To receive deliveries, subscribe to the `truemed_session.truemed_review_complete` event type. Channels that aren't subscribed get nothing. ### Example delivery ```json { "webhook_delivery_id": "dlv_f3a91c0b7d2e485fa6b19c04d7e2513a", "event_type": "truemed_session.truemed_review_complete", "occurred_at": "2026-07-01T18:45:00Z", "data": { "truemed_session_id": "ts_01JZ7D4M3A8B9C0D1E2F3G4H5J", "user_id": "shopify_customer_7001", "qualification_status": "approved", "is_testing": false, "created_at": "2026-07-01T18:30:00Z" }, "metadata": "{\"order_ref\":\"1001\"}" } ``` **Authentication**: Requests are HMAC-SHA256 signed. The `x-truemed-signature` header carries a timestamp and the signature in the form `t=<unix-timestamp>,v0=<hex-signature>`. To verify: take the `t` value from the header, compute HMAC-SHA256 over `<t>.<raw-request-body>` with your webhook signing secret, and compare the hex digest to the `v0` value. Sign the raw body bytes exactly as received, since re-serializing the JSON changes the bytes and breaks the signature. ## Request Notes The payload is a signed envelope: - `webhook_delivery_id` - Deterministic delivery id. Retries of the same delivery repeat the same value, so use it to deduplicate. - `event_type` - Which event this is, one of `truemed_session.pending_authorization` or `truemed_session.truemed_review_complete`. - `occurred_at` - ISO-8601 timestamp of when the event occurred. - `data` - A compact session summary: the session id, user id, qualification status at event time, and session metadata needed for correlation. Read the session for the full qualification and cart picture. - `metadata`: **(Optional)** - JSON-encoded string echoing whatever metadata the merchant supplied at session creation. Omitted if none was supplied. ## Response Notes ### Success Case HTTP Status: `204` You do not need to include any content in the body. ### Failure Case Truemed will retry the requests to your backend with backoff for up to 7 days

Payload

The payload of this webhook request is an object.

dataobjectRequired

Current Truemed session state.

event_typeenumRequired

Webhook event-type discriminator; the event name carries the qualification transition.

One of:

truemed_session.pending_authorization — The session entered pending_authorization after the shopper completed intake. Place the authorization hold on the card and signal it to start clinical review.
truemed_session.truemed_review_complete — Terminal: clinical review finished. Read the session and capture the hold for the qualified amount, which is eligible plus pre-approved when approved and the pre-approved portion only when rejected, then release the remainder.

occurred_atdatetimeRequired

When this event occurred.

webhook_delivery_idstringRequired

Deterministic delivery ID — retries of the same delivery repeat the same value; use it to deduplicate.

metadatastring or nullOptional

Opaque merchant metadata from session creation, when provided.

Response

204

Webhook received successfully (HTTP 204 No Content)

400

Invalid payload or authentication failure

500

Server error processing webhook