Webhooks

Webhooks permitem que seu backend receba notificações de eventos em vez de fazer polling. Você registra um endpoint HTTPS; a Telepatia envia por POST um envelope JSON assinado sempre que um evento assinado ocorre. Cada entrega é assinada com HMAC-SHA256 para que você possa provar que veio da Telepatia. Registre um webhook com POST /v1/webhooks; a resposta retorna um signingSecret uma única vez — guarde-o agora.

Events

Event catalog

Evento	Status	Dispara quando
`scribe_session.created`	Disponível	Uma nova sessão de scribe é criada
`scribe_session.completed`	Disponível	Uma sessão de scribe termina e seu registro médico está pronto
`scribe_session.error`	Disponível	Uma sessão de scribe falha ao processar
`scribe_session.updated`	Disponível	O registro de uma sessão já finalizada é editado depois
`scribe_session.cancelled`	Disponível	Uma sessão de scribe é descartada durante a gravação
`scribe_session.deleted`	Disponível	Uma sessão de scribe é excluída

Assine um ou mais eventos por webhook (o array events na criação).

Subscribing to events

Envie um array events ao registrar um webhook para escolher exatamente quais eventos ele recebe. O campo type de cada entrega indica qual evento disparou, então um único endpoint trata todo o ciclo.

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"]
  }'

Atualize a assinatura a qualquer momento com PATCH /v1/webhooks/{id} e um novo array events.

Event envelope

O corpo de cada POST de webhook é um envelope JSON. id é estável entre reentregas — deduplique por ele. data carrega o objeto de negócio do evento — para os eventos scribe_session.*, um instantâneo da sessão:

{
  "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"
  }
}

O objeto data para os eventos scribe_session.*:

Campo	Tipo	Descrição
`scribeSessionId`	string	Id público da sessão de scribe (`ss_…`).
`medicalRecordConfigurationId`	string \| null	Id público da configuração de registro médico usada (`mrc_…`). Mutuamente exclusivo com `scribeSessionConfigurationId`.
`scribeSessionConfigurationId`	string \| null	Id público da configuração de sessão de scribe usada (`ssc_…`). Mutuamente exclusivo com `medicalRecordConfigurationId`.
`status`	string	Status final da sessão — `completed`, `completedWithErrors`, `error`, `cancelled` ou `deleted`.
`institutionId`	string	Instituição dona da sessão.
`account`	object \| null	Profissional responsável — `id` (`acc_…`), `name`, `email`.
`patient`	object \| null	Paciente — `id`, `name` e identidade `idCountry` / `idType` / `idValue` (mesmos campos da requisição de set-consultation-context, para correlação).
`createdAt`	string	Quando a sessão foi criada (ISO 8601).
`completedAt`	string \| null	Quando a sessão terminou (ISO 8601); `null` para eventos de erro.

A mesma forma de data é enviada para cada evento scribe_session.*; status reflete o estado real da sessão e completedAt é null quando a sessão não foi concluída.

Verifying the signature

Cada requisição carrega um cabeçalho X-Scribe-Api-Signature (estilo Stripe):

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

t é o timestamp Unix em que a requisição foi assinada; v1 é o HMAC-SHA256 em hexadecimal de "{t}." + raw_request_body, com chave o seu segredo de assinatura. Verifique sobre o corpo cru da requisição antes de fazer o parse — reserializar o JSON pode mudar os bytes e quebrar a comparação. Use uma comparação de tempo constante e rejeite timestamps fora de uma janela de 5 minutos para mitigar ataques de repetição.

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

Cada requisição também carrega X-Scribe-Api-Event-Id (igual ao id do envelope) para log rápido.

Retry & delivery

Retorne um 2xx rapidamente para confirmar. Faça o trabalho lento de forma assíncrona.
Um 5xx, erro de rede ou timeout é repetido com backoff exponencial (≈2s até ≈2min entre tentativas) por até 6 tentativas ao longo de ~15 minutos.
Qualquer 4xx (incluindo 408 e 429) é tratado como permanente — a entrega não é repetida.
As repetições reutilizam o mesmo id do envelope, então deduplique por ele para ser idempotente.

Rotating the signing secret

Chame POST /v1/webhooks/{id}/rotate-secret para gerar um novo segredo. A resposta retorna o novo signingSecret uma única vez e incrementa signingSecretVersion. O segredo anterior para de verificar imediatamente, então implante o novo valor no seu endpoint antes de rotacionar.

Primeiros Passos

Consultas

Sessões de Scribe

Suporte à Decisão Clínica

Smart Templates

Templates de Sessão

Contas

Pacientes

Referência

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