Webhooks

Webhooks let your backend receive event notifications instead of polling. You register an HTTPS endpoint; Telepatia POSTs a signed JSON envelope to it whenever a subscribed event occurs. Every delivery is signed with HMAC-SHA256 so you can prove it came from Telepatia. Register a webhook with POST /v1/webhooks; the response returns a signingSecret once — store it now.

Events

Event catalog

Event	Status	Fires when
`scribe_session.created`	Live	A new scribe session is created
`scribe_session.completed`	Live	A scribe session finishes and its medical record is ready
`scribe_session.error`	Live	A scribe session fails to process
`scribe_session.updated`	Live	A finished session’s record is edited afterward
`scribe_session.cancelled`	Live	A scribe session is discarded mid-recording
`scribe_session.deleted`	Live	A scribe session is deleted

Subscribe to one or more events per webhook (the events array at creation).

Subscribing to events

Pass an events array when registering a webhook to choose exactly which events it receives. Each delivery’s type tells you which event fired, so a single endpoint can handle the whole lifecycle.

curl -X POST https://scribe-api.telepatia.ai/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/scribe",
    "events": ["scribe_session.created", "scribe_session.completed", "scribe_session.error"]
  }'

Update the subscription at any time with PATCH /v1/webhooks/{id} and a new events array.

Event envelope

Every webhook POST body is a JSON envelope. id is stable across redeliveries — dedupe on it. data carries the event’s business object — for scribe_session.* events, a snapshot of the session:

{
  "id": "evt_01HXAMPLE",
  "type": "scribe_session.completed",
  "createdAt": "2026-06-23T12:00:00Z",
  "data": {
    "scribeSessionId": "ss_01HXAMPLE",
    "medicalRecordConfigurationId": "mrc_01HXAMPLE",
    "scribeSessionConfigurationId": null,
    "status": "completed",
    "institutionId": "inst_01HXAMPLE",
    "account": {
      "id": "acc_01HXAMPLE",
      "name": "Dr. Juan Salazar",
      "email": "dr.salazar@clinica.com"
    },
    "patient": {
      "id": "pat_01HXAMPLE",
      "name": "María Pérez",
      "idCountry": "COLOMBIA",
      "idType": "CC",
      "idValue": "1023456789"
    },
    "createdAt": "2026-06-23T11:40:00Z",
    "completedAt": "2026-06-23T12:00:00Z"
  }
}

The data object for scribe_session.* events:

Field	Type	Description
`scribeSessionId`	string	Public id of the scribe session (`ss_…`).
`medicalRecordConfigurationId`	string \| null	Public id of the medical record configuration used (`mrc_…`). Mutually exclusive with `scribeSessionConfigurationId`.
`scribeSessionConfigurationId`	string \| null	Public id of the scribe session configuration used (`ssc_…`). Mutually exclusive with `medicalRecordConfigurationId`.
`status`	string	Final session status — `completed`, `completedWithErrors`, `error`, `cancelled`, or `deleted`.
`institutionId`	string	Institution that owns the session.
`account`	object \| null	Treating professional — `id` (`acc_…`), `name`, `email`.
`patient`	object \| null	Patient — `id`, `name`, and identity `idCountry` / `idType` / `idValue` (same fields as the set-consultation-context request, for correlation).
`createdAt`	string	When the session was created (ISO 8601).
`completedAt`	string \| null	When the session finished (ISO 8601); `null` for error events.

The same data shape is sent for every scribe_session.* event; status reflects the actual session state and completedAt is null when the session did not complete.

Verifying the signature

Each request carries an X-Scribe-Api-Signature header (Stripe-style):

X-Scribe-Api-Signature: t=1750000000,v1=5257a869e7ec...

t is the Unix timestamp the request was signed at; v1 is the hex HMAC-SHA256 of "{t}." + raw_request_body, keyed by your signing secret. Verify over the raw request body before parsing — re-serializing JSON can change the bytes and break the comparison. Use a constant-time compare and reject timestamps outside a 5-minute window to blunt replay attacks.

import hashlib
import hmac
import time

def verify(secret: str, header: str, raw_body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, v1 = parts["t"], parts["v1"]
    signed = f"{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1) and abs(time.time() - int(t)) <= 300

Each request also carries X-Scribe-Api-Event-Id (equal to the envelope id) for quick logging.

Retry & delivery

Return a 2xx quickly to acknowledge. Do slow work asynchronously.
A 5xx, network error, or timeout is retried with exponential backoff (≈2s up to ≈2min between attempts) for up to 6 attempts across ~15 minutes.
Any 4xx (including 408 and 429) is treated as permanent — the delivery is not retried.
Retries reuse the same envelope id, so dedupe on it to stay idempotent.

Rotating the signing secret

Call POST /v1/webhooks/{id}/rotate-secret to generate a new secret. The response returns the new signingSecret once and bumps signingSecretVersion. The previous secret stops verifying immediately, so roll the new value out to your endpoint before rotating.

Getting Started

Consultations

Scribe Sessions

Clinical Decision Support

Smart Templates

Session Templates

Accounts

Patients

Reference

Webhooks

Events

Event catalog

Subscribing to events

Event envelope

Verifying the signature

Retry & delivery

Rotating the signing secret

​Events

​Event catalog

​Subscribing to events

​Event envelope

​Verifying the signature

​Retry & delivery

​Rotating the signing secret

Events

Event catalog

Subscribing to events

Event envelope

Verifying the signature

Retry & delivery

Rotating the signing secret