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’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:

{
  "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