Webhooks - Westhetics · Desenvolvedores

Um webhook é um endereço do seu sistema que recebe os eventos da clínica assim que eles acontecem. Em vez de perguntar a cada minuto se a paciente assinou, o seu sistema fica sabendo no momento da assinatura.

Eventos

O catálogo completo, com o que vem em data em cada um.

Verificar a assinatura

O padrão Standard Webhooks, com exemplos em Node, Python, PHP e Go.

Tentativas e falhas

O que acontece quando o seu endereço não responde.

Testar

“Enviar teste” e o evento webhook.test.

Cadastrar

O webhook pertence a um app. Há dois caminhos:

Pela tela. A gestora abre o app em Integrações › Webhooks › + Novo webhook, com o endereço, uma descrição e os eventos.
Pela API. O app com o escopo Gerenciar os próprios webhooks pela API cria, altera e remove os próprios webhooks. Veja webhooks pela API.

Cada app tem até 5 webhooks. Cada um recebe todos os eventos que o app pode ver (["*"]) ou uma lista do catálogo.

O endereço

https://, na porta 443, com nome de domínio público (https://crm.exemplo.com.br/webhooks/westhetics).
IP, localhost, rede interna (.local, .internal, .test) e endereços da Westhetics não recebem.
Até 2.048 caracteres. Não ponha segredo no caminho: a tela e a trilha mostram o domínio.

O que chega

POST /webhooks/westhetics HTTP/1.1
Host: crm.exemplo.com.br
Content-Type: application/json
User-Agent: Westhetics-Webhooks/1.0
webhook-id: 3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d
webhook-timestamp: 1792081867
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{
  "id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "type": "signature_request.completed",
  "createdAt": "2026-10-15T14:31:07Z",
  "clinicId": "0b9a8c7d-6e5f-4a3b-2c1d-0e9f8a7b6c5d",
  "actor": { "type": "system", "id": null },
  "data": {
    "signatureRequestId": "5d6e7f80-91a2-4b3c-8d4e-5f6a7b8c9d0e",
    "appointmentId": "3c9d1e2f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "patientId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "protocolNumber": "WX-4472-BM",
    "documentIds": ["d4e5f6a7-b8c9-4123-8ef4-567890123456"]
  }
}

Campo	O quê
`id`	o id do evento; o mesmo em `webhook-id` e em toda nova tentativa
`type`	o tipo, do catálogo
`createdAt`	quando aconteceu
`actor`	quem fez: `user` (pessoa da clínica), `integration` (um app), `patient` (pelo link), `provider` (a Autentique) ou `system`
`data`	os ids e o essencial; o resto se lê pela API

O evento é fino de propósito: não carrega o cadastro da paciente nem o conteúdo do documento. Quem recebe busca o recurso pela API, com os escopos do app, e sempre vê o estado atual.

O que o seu endereço faz

Confira a assinatura

Com o corpo cru, antes de interpretar o JSON. Veja verificar a assinatura.

Ignore o repetido

Guarde o webhook-id dos eventos já tratados. A mesma entrega pode chegar mais de uma vez.

Responda 2xx em até 10 segundos

Ponha o trabalho numa fila e responda. Redirecionamento não é seguido: um 301 conta como falha.

A ordem de chegada não é garantida. Ordene por createdAt e trate cada evento como um aviso de que algo mudou, não como o estado inteiro.

Eventos também pela API

Os eventos ficam 30 dias em GET /v1/events, em ordem de acontecimento. Serve para recuperar o que o seu endereço perdeu fora do ar, ou para quem não pode receber webhook:

curl -G https://api.westhetics.io/v1/events \
  -H "Authorization: Bearer $WESTHETICS_API_KEY" \
  --data-urlencode "types=anamnesis.completed,signature_request.completed" \
  --data-urlencode "limit=100"