Truemed calls your endpoint when an open dispute's state or phase changes — for example, after you submit evidence and it moves to under_review. An update that changes neither state nor phase is silent.

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>. 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.

Payload

The signed body is the standard Truemed envelope:

• webhook_delivery_id - Delivery id (dlv_…). Retries of the same event repeat the same value; use it to deduplicate.
• event_type - The wire event name (dispute.created, dispute.updated, or dispute.closed).
• data - The full canonical dispute, the same shape returned by GET /api/v1/disputes/{dispute_id} — including dispute_id, state, phase, reason, amount, due_by, counters, and metadata. Null fields are omitted. Payloads carry canonical Truemed fields and the public dispute_id UUID only, never raw processor shapes. Always key your records on dispute_id.

(Unsigned legacy endpoints receive the data object as the flat top-level body, with no envelope and no event_type.)

The model is notify, then fetch: the snapshot is complete enough to act on directly, and you can re-fetch the dispute for authoritative state when a delivery is delayed or retried out of order.

Inquiries notify too, with one exception. A live inquiry fires dispute.created / dispute.updated just like a chargeback, so you can respond to pre-empt its escalation. If the bank later drops a surfaced inquiry, the terminal closed state fires dispute.closed — so dispute.closed marks any terminal outcome, whether a chargeback result (won / lost / accepted / expired) or a dropped inquiry (closed). The only silent case is an inquiry that opens and closes between webhook deliveries — already terminal the first time Truemed sees it — which fires no webhook.

Response Notes

Return HTTP 204 with an empty body. Truemed retries failed deliveries with backoff for up to 7 days.