Truemed Session Updated Webhook
Stay in sync with your Truemed sessions without polling: Truemed calls your endpoint whenever a
session changes. The `truemed_session.updated` event fires at three moments:
- **Clinical review begins** — `data.qualification_info.qualification_status` moves to
`pending_truemed_review` (`context.new_qualification_status` is set). The early signal that lets you
kick off downstream work before review completes.
- **A terminal result** — a qualification decision (`approved` / `partially_approved` /
`rejected`) or a cancellation (`context.new_qualification_status` = `canceled`).
- **A payment change you report** — a capture or refund, which moves the cumulative
`data.captured_amount_cents` / `data.refunded_amount_cents`.
Subscribe to the
`truemed_session.updated` event type to receive deliveries; channels that don't subscribe
receive nothing.
**Authentication**: Requests are HMAC-SHA256 signed. Verify the `x-truemed-signature` header
against the raw request body using your webhook signing secret.
## Request Notes
The payload is a signed envelope:
- `webhook_delivery_id` - Deterministic delivery id — retries of the same delivery repeat the same value; use it to deduplicate.
- `event_type` - The wire-type discriminator, an enum with (today) the single value
`truemed_session.updated`.
- `occurred_at` - ISO-8601 timestamp of when the event occurred.
- `data` - The compact session summary: the qualification info (`data.qualification_info`), the
cart split (`data.cart_info`), and the cumulative `data.captured_amount_cents` /
`data.refunded_amount_cents`. Event names never carry state — read the states from the
payload.
- `context` - The status transition this delivery announces. `context.new_qualification_status`
**(Optional)** is set when this delivery announces a qualification transition (including
cancellation): the value `data.qualification_info.qualification_status` just moved to. Omitted on
payment-only deliveries.
- `metadata`: **(Optional)** - JSON-encoded string echoing whatever metadata the merchant
supplied at session creation. Omitted if none was supplied.
### Example delivery — the terminal money gate
```json
{
"webhook_delivery_id": "whd_01JZ7E8Q2K4M6N8P0R2T4V6X8Z",
"event_type": "truemed_session.updated",
"occurred_at": "2026-07-01T18:45:00Z",
"context": {
"new_qualification_status": "approved"
},
"data": {
"truemed_session_id": "ts_01JZ7D4M3A8B9C0D1E2F3G4H5J",
"user_id": "shopify_customer_7001",
"qualification_info": {
"qualification_status": "approved",
"is_already_qualified": false
},
"cart_info": {
"cart_type": "all_eligible",
"eligible_amount_cents": 11850,
"ineligible_amount_cents": 0,
"preapproved_amount_cents": 0
},
"captured_amount_cents": 0,
"refunded_amount_cents": 0,
"is_testing": false,
"created_at": "2026-07-01T18:30:00Z"
},
"metadata": "{\"order_ref\":\"1001\"}"
}
```
`context.new_qualification_status` is present on most deliveries — every review-start, terminal,
and cancellation delivery announces its transition there. Only payment-only deliveries (a capture
or refund you report) omit it.
## Response Notes
### Success Case
HTTP Status: `204`
The partner does 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