End-to-end example

This page shows the full flow with Tiep UI and a webhook.

The goal:

A doctor opens Tiep from the HIS, records the visit, saves the report, and the HIS receives the structured data.

Step 1: create a facility

Every consultation belongs to a facility.

Read onboarding and facilities first.

Step 2: create a webhook

In the platform, open the facility and configure integration settings.

You need:

• Webhook URL.
• Webhook secret.
• Payload type.

Example webhook URL:

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

Step 3: generate a launch token

The HIS asks Tiep for a short-lived token. This token lets the doctor open Tiep without typing a password.

curl -X POST "https://api.tiep.ai/v1/auth/generate-token" \
  -H "X-API-Key: $FACILITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "doctor": {
      "id": "doctor-123",
      "name": "Dr. Anna Smith",
      "specialties": ["ORTHOPEDICS"]
    },
    "create_session": true,
    "form": {
      "title": "Anamnesis",
      "type": "object",
      "properties": {
        "reason": {
          "title": "Reason for visit",
          "type": "string",
          "description": "Why the patient came today"
        },
        "pain-level": {
          "title": "Pain level",
          "type": "integer",
          "description": "Pain level from 0 to 10",
          "minimum": 0,
          "maximum": 10
        }
      }
    }
  }'

Response:

{
  "token": "qKaIW2jUWEFT841tP_vMYoswTAXiejtPgqf3sHQ90iY",
  "session_id": "60c478df-2e8d-4317-90af-d801c217a034"
}

Step 4: build the Tiep URL

The HIS opens Tiep with query parameters.

https://app.tiep.ai/?token=<token>&session_id=<session_id>&context=<base64-json>

The context is patient and visit metadata encoded as URL-safe Base64 JSON.

Minimum useful context:

{
  "patient": {
    "resourceType": "Patient",
    "identifier": [
      {
        "value": "patient-123"
      }
    ],
    "name": [
      {
        "text": "John Smith"
      }
    ]
  },
  "visit_id": "visit-456"
}

Python helper:

import json
from base64 import urlsafe_b64encode
from urllib.parse import urlencode


def build_tiep_url(token: str, session_id: str, context: dict) -> str:
    encoded_context = urlsafe_b64encode(json.dumps(context).encode()).decode()
    query = urlencode(
        {
            "token": token,
            "session_id": session_id,
            "context": encoded_context,
        }
    )
    return f"https://app.tiep.ai/?{query}"

danger

Always include context. The doctor cannot save a consultation without patient context.

Step 5: receive the report

When the doctor saves, Tiep calls your webhook.

Your endpoint should:

• Read the raw request body.
• Verify the signature.
• Store the payload.
• Return 200 OK.

import hmac
import json
from hashlib import sha256


def handle_tiep_webhook(raw_body: bytes, signature: str, secret: str) -> dict:
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"),
        msg=raw_body,
        digestmod=sha256,
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        raise ValueError("Invalid Tiep signature")

    return json.loads(raw_body)

Step 6: poll session status if needed

If you created a session, your HIS can poll it.

curl "https://api.tiep.ai/v1/sessions/60c478df-2e8d-4317-90af-d801c217a034" \
  -H "X-API-Key: $FACILITY_API_KEY"

Example response after save:

{
  "id": "60c478df-2e8d-4317-90af-d801c217a034",
  "status": "report_saved",
  "payload": {
    "context": {
      "visit_id": "visit-456"
    },
    "payload": {
      "reason": "Shoulder pain after tennis",
      "pain-level": 6
    }
  }
}