Truemed Session Pending Authorization Webhook

Truemed calls your endpoint when the shopper finishes intake and the session reaches pending_authorization. Place the authorization hold on the shopper’s card on your own rail, then signal it with the auth-hold endpoint. That starts clinical review.

This event fires only on that path. It does not fire when:

the cart is fully pre-approved, because it reaches pending_authorization on the create response instead, or
you place the hold before the shopper takes the survey (hold-first), because the session skips pending_authorization and goes straight from pending_user_intake to pending_truemed_review.

In both cases, read qualification_status on the return GET instead of waiting for this event; the GET is always authoritative. To receive deliveries, subscribe to the truemed_session.pending_authorization event type; channels that aren’t subscribed get nothing.

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 when the shopper finishes intake and the session reaches `pending_authorization`. Place the authorization hold on the shopper's card on your own rail, then signal it with the auth-hold endpoint. That starts clinical review. This event fires only on that path. It does **not** fire when: - the cart is fully pre-approved, because it reaches `pending_authorization` on the create response instead, or - you place the hold before the shopper takes the survey (hold-first), because the session skips `pending_authorization` and goes straight from `pending_user_intake` to `pending_truemed_review`. In both cases, read `qualification_status` on the return `GET` instead of waiting for this event; the `GET` is always authoritative. To receive deliveries, subscribe to the `truemed_session.pending_authorization` event type; channels that aren't subscribed get nothing. **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