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
the session reuses an existing LMN and does not need new intake or clinical review.

When intake is required, it must finish before you place the authorization hold. The hold is the final merchant step that starts clinical 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.
data - Exactly five fields: truemed_session_id, user_id, the qualification status at event time, is_testing, and the Truemed Session’s created_at timestamp. Read the session for the full qualification and cart picture.

The signature header’s t value is the delivery timestamp. The JSON envelope does not include an event-occurrence timestamp or top-level metadata.

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 - the session reuses an existing LMN and does not need new intake or clinical review. When intake is required, it must finish before you place the authorization hold. The hold is the final merchant step that starts clinical 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`. - `data` - Exactly five fields: `truemed_session_id`, `user_id`, the qualification status at event time, `is_testing`, and the Truemed Session's `created_at` timestamp. Read the session for the full qualification and cart picture. The signature header's `t` value is the delivery timestamp. The JSON envelope does not include an event-occurrence timestamp or top-level metadata. ## 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.

webhook_delivery_idstringRequired

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

Response

204

Webhook received successfully (HTTP 204 No Content)

400

Invalid payload or authentication failure

500

Server error processing webhook