Item Eligibility Updated Webhook
The partner can implement an endpoint that Truemed calls when the HSA/FSA eligibility status
of an item changes.
This webhook is triggered when:
1. An item's eligibility is updated (e.g., from `ineligible` to `eligible_with_lmn`)
2. An item is reviewed and its eligibility status is determined
**Authentication**: Signed webhooks are HMAC-SHA256 signed. The `x-truemed-signature` header carries a
timestamp and the signature in the form `t=<unix-timestamp>,v0=<hex-signature>`. Compute HMAC-SHA256 over
`<t>.<raw-request-body>` with your webhook signing secret and compare the hex digest to `v0`. Sign the raw
body bytes exactly as received, since re-serializing the JSON changes the bytes and breaks the signature.
Unsigned (legacy) webhooks instead send the API key verbatim in the `x-truemed-api-key` header.
## Request Notes
The signed body wraps an event envelope inside the delivery envelope, so the catalog item is at
`data.data.object`:
```json
{
"webhook_delivery_id": "dlv_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"event_type": "product_catalog.item.eligibility_updated",
"data": {
"event_type": "product_catalog.item.eligibility_updated",
"timestamp": "2026-01-15T12:00:00Z",
"data": {
"object": {
"sku": "ITEM-001",
"name": "Compression Knee Brace",
"eligibility": "eligible_with_lmn",
"reviewed_at": "2026-01-15T11:59:58Z"
}
}
}
}
```
Fields:
- `webhook_delivery_id` - Delivery id (`dlv_…`). Retries of the same event repeat the same value; use it to
deduplicate. Signed deliveries only.
- `event_type` - The event type identifier: `product_catalog.item.eligibility_updated`. Carried on both the
delivery envelope and the inner event envelope, with the same value.
- `data.timestamp` - ISO-8601 timestamp of when the event occurred
- `data.data.object` - The item details including:
- `sku` - The SKU of the item
- `name` - The name of the item
- `eligibility` - The HSA/FSA eligibility status:
- `eligible` - Item is default eligible for HSA/FSA
- `eligible_with_lmn` - Item is eligible with a Letter of Medical Necessity
- `ineligible` - Item is not eligible for HSA/FSA
- `reviewed_at` - ISO-8601 timestamp of when the item was last reviewed
Unsigned (legacy) webhooks receive the inner event envelope as the top-level body — `{event_type,
timestamp, data: {object}}` — with no `webhook_delivery_id`. The item is at `data.object`.
## 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