> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://developers.truemed.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.truemed.com/_mcp/server.

# Item Eligibility Updated Webhook

POST 

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's eligibility status is first 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's eligibility was last decided

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

Reference: https://developers.truemed.com/api-reference/product-catalog/item-eligibility-updated-webhook

## Request

### Payload

- `data` (ProductCatalogItemEligibilityUpdatedEventEnvelope, required) — The event envelope, carrying `event_type` and `timestamp`. The catalog item itself is at `data.data.object`.
- `event_type` (string, required) — The event type: `product_catalog.item.eligibility_updated`.
- `webhook_delivery_id` (string, required) — Deterministic idempotency key for this delivery (`dlv_…`); stable across retries.

## Types

### ProductCatalogItemEligibilityUpdatedEventEnvelope

- `data` (ProductCatalogItemEligibilityUpdatedWebhookData, required) — The webhook payload data.
- `event_type` (string, required) — The type of event that triggered this webhook (e.g., 'product_catalog.item.eligibility_updated').
- `timestamp` (string, required) — ISO-8601 timestamp of when the event occurred.

### ProductCatalogItemEligibilityUpdatedWebhookData

- `object` (CatalogItemDetail, required) — The catalog item with updated eligibility information.

### CatalogItemDetail

- `created_at` (datetime, required) — The date and time the catalog item was created.
- `name` (string, required) — The name of the catalog item.
- `sku` (string, required) — The SKU of the catalog item.
- `comparable_item_price_cents` (integer, optional, nullable) — The amount, in cents, deducted from each unit of this item before any of it can reach an HSA/FSA card.
- `description` (string, optional, nullable) — An optional description of the catalog item.
- `eligibility` (enum, optional, nullable) — HSA/FSA eligibility status for the catalog item.
  - Allowed values: `eligible`, `eligible_with_lmn`, `ineligible`
- `gtin` (string, optional, nullable) — The GTIN of the catalog item.
- `image_urls` (list of string, optional, nullable) — Optional array of image URLs associated with the catalog item.
- `metadata` (string, optional, nullable) — Optional metadata string for the catalog item.
- `product_id` (string, optional, nullable) — The product ID of the product which this catalog item is a variant of.
- `reviewed_at` (datetime, optional, nullable) — The date and time the catalog item's eligibility was last decided. Present whenever `eligibility` is.
- `url` (string, optional, nullable) — An optional display page URL for the catalog item.