# Patient data in your calls and webhooks

> Where patient data lives in a Rivr integration, what comes back and what doesn't — and the one rule that saves you the most trouble.

You integrate a journal system for clinics that treat patients. An order carries the most sensitive thing a system can hold: who the patient is and what they have done. This guide shows exactly where that data goes through Rivr, so you don't spread it where it doesn't belong — and so you know where you may actually read it back.

- Market: Sweden (`se`). Norway differs in currency, payment methods and what happens when nobody pays: https://developers.rivr.io/guides/patient-data.md?market=no
- Language: English (`en`). Svenska: https://developers.rivr.io/guides/patient-data.md?lang=sv
- 6 min read · 6 steps
- Page in the portal: https://developers.rivr.io/guides/patient-data

Every example targets the sandbox (`https://api.test.rivr.io`) and needs test credentials. A platform client's tokens come from `https://auth.test.rivr.io`, an organisation key's from `https://auth.test.rivr.tech`.

## 1. The personal number identifies the payer — it isn't echoed back

*Journal system → Rivr*

You send `personalNumber` when you create the order. Rivr uses it to identify the payer against a population register: usually the patient, the guardian when they pay for a child. It is not returned in any webhook. The only place the number is disclosed is a full order read in `/api/public` (`public:orders:read`), and then in clear text. So don't build your patient link on the webhook — keep your own id.

**Why:** The number should live in one place: with you, tied to your own patient id. The fewer paths it takes, the less can leak.

**What your system does:** Send the number to create the order, then look the patient up on your own order id or your `reference` when the webhook arrives.

## 2. Reference and metadata come back verbatim

*Rivr → Journal system*

What you put in `reference` and `metadata` on the order is echoed unchanged in every order webhook, and also travels on to settlement rows and the invoice's external reference. They are not masked in logs, and they are not cleared when an order is erased. They are meant for your own ids, not for anything about the patient.

**Why:** These two fields are the only ones in the whole flow that you fill freely and that move unmasked through webhooks, settlement and invoicing. What lands there is hard to get out again.

> **Rule.** Never put patient data in `reference` or `metadata` — no personal number, no name, no treatment. Use an internal id (visit id, booking id) and look the patient up on your side.

## 3. The treatment text may be hidden

*Clinic*

An order line's description can say what the patient has done. For a clinic Rivr has set up for it, Rivr encrypts the description and shows a generic label instead — "Behandling / Åtgärd" (treatment) or "Avdrag/Rabatt" (discount). You can turn that off per order with the checkout hint `disableDescriptionEncryption`. The webhook carries no order lines at all, so the description never reaches you that way.

> **Note.** The encryption is the clinic's setting, not a guarantee on every order: without it the text is shown in clear, and you can opt out. The patient sees their own text in checkout, and a clinic user with the right permission can fetch a receipt with clear text — which is logged as a disclosure.

## 4. The webhook carries no patient data

*Rivr → Journal system*

An order webhook carries the order's id and status, dates, payment method, and your `reference` and `metadata` — and no personal number, no name, no contact details, no address, no amount and no order lines. It is signed with HMAC-SHA256 in `Rivr-Signature` when the clinic or platform has an active key (otherwise unsigned), and carries `Rivr-Webhook-Id`. Subscription webhooks carry neither `reference` nor `metadata`.

**What your system does:** Trust the webhook for status. If you need patient data, fetch it with an authorised call (next step) — never derive it from the webhook.

## 5. Read patient data back with the right permission

*Journal system → Rivr*

The capability `orders:read` alone gives only the order's id and status. Patient data sits behind `customers:read`, which Rivr classes as health data. A full order read in `/api/public` (`public:orders:read`) returns the whole customer block including the personal number. Ask only for the permissions you actually use.

> **Note.** `customers:read` is health data. A key that only needs to confirm an order is paid doesn't need it — `orders:read` is enough, and then the key never reaches any patient data.

## 6. Protected identity

*Rivr*

For a patient with a protected identity, the personal number is masked in `/api/public` to `ÅÅMMDD-****` and name, phone and email to the first character, and the address is emptied. The birth date remains, so a masked identity is not anonymous — handle it as personal data.

## Common pitfalls

- Putting a personal number or name in `reference` or `metadata`. They are echoed in the webhook, travel on to settlement and invoice, aren't masked and aren't cleared on erasure.
- Expecting patient data in the webhook. It never carries a name, personal number or order lines — fetch them with an authorised call instead.
- Assuming every treatment text is hidden. The encryption is the clinic's setting, and you can opt out per order.
- Treating a masked protected identity as anonymous. The birth date remains — it is still personal data.

## Next guide

- [Receive webhooks](https://developers.rivr.io/guides/webhooks.md): The webhook is the truth about an order. How to receive it safely, and only once.
- [Verify the webhook signature](https://developers.rivr.io/guides/verify-signatures.md): Code in Node, PHP, Python and .NET, pseudocode for Delphi and 4D, and test vectors to prove your own code against.
- [Patients who can't be identified](https://developers.rivr.io/guides/unidentified-patients.md): Protected identity, personal numbers the register can't find, orders without a personal number and children whose guardian pays: when Rivr requires an identified payer, what happens when it can't, and what your system should show.