Integration settings

Integration settings connect a facility to your HIS.

HIS means hospital information system. It is the system where the final report should be stored.

What you configure

Setting	What it does
Webhook URL	Where Tiep sends saved reports.
Webhook secret	Shared secret used to sign the payload.
Payload type	The format sent to your HIS.
Allow registered doctors	Lets doctors signed in with email start without an API launch token.
Require launch context	Requires a JSON context object before a consultation can be saved.
Required context keys	Optional list of top-level keys that must have a non-null value.

Who can start a consultation

There are two kinds of doctor in Tiep:

Kind	How they sign in
API-token doctor	Your HIS calls /v1/auth/generate-token and opens Tiep with the token it returns.
Registered doctor	The person signs in with their own email and picks a doctor profile.

Once a facility has a webhook, only API-token doctors can start consultations. That is the strict default, and it is what keeps every report traceable to a launch your HIS made.

Turn on Allow registered doctors to also let email-signed-in doctors start on their own.

warning

Signing in with a one-time code is not the same as an API launch. The token has to come from /v1/auth/generate-token, because that call is what creates the session and ties it to the token.

Facilities without a webhook are not affected by any of this. Any doctor can start there.

Consultation requirements

Turn on Require launch context and Tiep refuses a consultation that arrives without a context object. Add required context keys and Tiep also checks that those keys carry a value.

What you configure	What a consultation needs
Require launch context off	Nothing. Any leftover key list is ignored.
Require launch context on, no keys	Any JSON object, even an empty {}.
Require launch context on, keys listed	Every listed key, at the top level, with a value that is not null.

A key counts as supplied unless it is missing or null. An empty string, false and 0 all pass, so send null when you mean "we do not have this."

The doctor sees exactly which keys are missing, so name them the way your team would.

Webhook URL

Use an HTTPS endpoint controlled by your system. Reports are clinical data, so plain http:// is a bad idea even where it happens to be accepted.

Example:

https://his.example.com/tiep/webhooks/consultations

When a doctor saves a report, Tiep sends an HTTP POST request to that URL.

Webhook secret

The secret proves the request came from Tiep. It must be at least 16 characters.

Once saved, Tiep never shows it again. Leave the field blank when you edit the other settings and the current secret is kept; type a new one only when you mean to replace it.

Tiep sends this header:

X-Signature-256: sha256=<digest>

Your HIS should calculate the same digest using the raw request body and the secret.

import hmac
from hashlib import sha256


def is_valid_signature(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"),
        msg=raw_body,
        digestmod=sha256,
    ).hexdigest()
    return hmac.compare_digest(header, expected)

Payload type

Choose the payload type based on what your HIS wants. The platform offers two:

Payload type	Shown as	Use it when
SIMPLE	Simple	You want simple JSON that mirrors the form answers.
HL7_V2	HL7 FHIR	You want a FHIR-style bundle.

Older integrations may still be set to HL7_V1_0, which Tiep keeps working but no longer offers. If your facility is on it, talk to us before changing anything.

Read payload format for examples.

Consultation context

Context means the data your HIS attaches to a session when it opens Tiep.

You pass it as a JSON object, encoded with URL-safe Base64, in the context query parameter of the launch URL. Read step 4 of the end-to-end example for how to build that URL.

A few keys have special meaning to Tiep. Every other key is echoed back unchanged in the saved payload, so you can use context to carry your own identifiers.

Special keys

Key	Type	What Tiep does with it	In the returned context
doctor_id	String	Reserved. Whatever you send is discarded, and Tiep writes the internal ID of the doctor who saved the report.	Always, written by Tiep
patient	FHIR Patient or { "internal_id": "..." }	Identifies the patient. In the HL7 payload types a FHIR patient is also built into the bundle.	Yes, unchanged
episode	FHIR EpisodeOfCare or { "title": "..." }	Identifies the visit.	Yes, unchanged
history	String	Shown to the doctor as clinical background and given to the AI as patient context. The AI uses it to avoid repeating what is already known and to better understand the visit.	No

Keys not in this table travel through Tiep untouched. For example, if you send "visit_id": "visit-456", you get it back inside context.

Because doctor_id is reserved, you cannot list it as a required context key.

tip

Think of context as the note you pin to the consultation so your webhook knows where to file the report. history is the one key that does not work that way: it is background reading for the doctor and the AI, and it never comes back. You can still require it, but require something like visit_id for the actual filing.

Example

Context the HIS sends:

{
  "patient": {
    "resourceType": "Patient",
    "identifier": [{ "value": "patient-123" }],
    "name": [{ "text": "John Smith" }]
  },
  "episode": {
    "resourceType": "EpisodeOfCare",
    "identifier": [{ "value": "episode-789" }],
    "patient": { "reference": "Patient/patient-123" },
    "status": "active"
  },
  "history": "65-year-old female. Type 2 diabetes, hypertension. Allergic to penicillin.",
  "visit_id": "visit-456",
  "department": "orthopedics"
}

context block returned in the SIMPLE payload:

{
  "doctor_id": "doctor-123",
  "patient": {
    "resourceType": "Patient",
    "identifier": [{ "value": "patient-123" }],
    "name": [{ "text": "John Smith" }]
  },
  "episode": {
    "resourceType": "EpisodeOfCare",
    "identifier": [{ "value": "episode-789" }],
    "patient": { "reference": "Patient/patient-123" },
    "status": "active"
  },
  "visit_id": "visit-456",
  "department": "orthopedics"
}

Three things changed on the way out:

• doctor_id was added, naming the doctor who saved the report.
• history was dropped. The doctor and the AI saw it, but your HIS already has it.
• Everything else came back exactly as you sent it.

When you send no patient or episode

If you leave patient or episode out, Tiep fills in from its own records when it safely can:

Field	Fallback Tiep may add	When it stays empty
patient	{ "internal_id": "..." }	No patient is linked to the session.
episode	{ "title": "..." }	No episode is linked, or the title is encrypted so Tiep cannot read it.

Tiep never puts its own database IDs, your external_id, or encrypted text in these fallbacks.

Naming the patient at launch instead

context is not the only way to say who the visit is for. When you ask for the launch token, /v1/auth/generate-token takes patient and episode of its own:

{
  "doctor": { "id": "doctor-123" },
  "patient": { "internal_id": "MRN-12345" },
  "episode": { "external_id": "EP-2026-KNEE" }
}

The difference is worth knowing:

Where you put it	What it does
On the launch token	Links the session to a real patient and episode in Tiep's registry, before the doctor says a word.
In context	Rides along with the visit and comes back in the webhook.

Use the token fields when you want the visit grouped in Tiep, and context when you want your own identifiers echoed back. Doing both is fine. Read patients and episodes for what the registry needs turned on first.

Two integration styles

Tiep UI style

Use this when doctors open Tiep.

Direct API style

Use this when your product owns the UI.

The same facility can support both styles if your workflow needs it.