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.

Webhook URL

This must be an HTTPS endpoint controlled by your system.

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.

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.

Payload type	Use it when
SIMPLE	You want simple JSON that mirrors the form answers.
CUSTOM	You want simple JSON with custom handling.
HL7_V1_0	You need the older HL7 payload used by legacy integrations.
HL7_V2	You want a FHIR-style bundle.

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	Echoed back
patient	FHIR Patient resource	Identifies the patient. Embedded inside HL7 and FHIR bundles when the payload type needs them.	No
episode	FHIR EpisodeOfCare resource	Identifies the visit. Embedded inside HL7 and FHIR bundles when the payload type needs them.	Yes
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.

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:

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

patient and history do not appear in the echoed context. patient is delivered through HL7 and FHIR Patient resources in the HL7 payload types. history is shown to the doctor and given to the AI as context, but it is not echoed back because your HIS already has it.

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.