> ## Documentation Index
> Fetch the complete documentation index at: https://docs.westhetics.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> A Westhetics manda um POST assinado para o seu endereço a cada evento da clínica: ficha criada, anamnese respondida, contrato assinado.

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.

> [card] [Eventos](https://docs.westhetics.io/webhooks/eventos.md)
>
> O catálogo completo, com o que vem em `data` em cada um.

> [card] [Verificar a assinatura](https://docs.westhetics.io/webhooks/verificar-assinatura.md)
>
> O padrão Standard Webhooks, com exemplos em Node, Python, PHP e Go.

> [card] [Tentativas e falhas](https://docs.westhetics.io/webhooks/tentativas.md)
>
> O que acontece quando o seu endereço não responde.

> [card] [Testar](https://docs.westhetics.io/webhooks/testar.md)
>
> "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](https://docs.westhetics.io/webhooks/pela-api.md).

Cada app tem até **5 webhooks**. Cada um recebe todos os eventos que o app pode ver (`["*"]`) ou uma lista do [catálogo](https://docs.westhetics.io/webhooks/eventos.md).

### 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

```http theme={null}
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](https://docs.westhetics.io/webhooks/eventos.md) |
| `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

**1. Confira a assinatura**

Com o corpo cru, antes de interpretar o JSON. Veja [verificar a
assinatura](https://docs.westhetics.io/webhooks/verificar-assinatura.md).

**2. Ignore o repetido**

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

**3. Responda 2xx em até 10 segundos**

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

> [!NOTE]
>
> 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:

```bash theme={null}
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"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.