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

> O app com o escopo de webhooks cria, altera, testa e remove os próprios webhooks, e acompanha as entregas, pela API.

Plataformas de automação e sistemas que se configuram sozinhos criam o webhook na hora em que o cliente liga a integração, e removem quando desliga. Para isso o app precisa do escopo **Gerenciar os próprios webhooks pela API** (`webhooks:write`). Um app só vê e mexe nos webhooks dele.

| Rota | O quê |
| - | - |
| `GET /v1/webhooks` | os webhooks do app |
| `POST /v1/webhooks` | cria; a resposta traz o segredo |
| `GET /v1/webhooks/{id}` | um webhook |
| `PATCH /v1/webhooks/{id}` | muda endereço, descrição, eventos ou status |
| `DELETE /v1/webhooks/{id}` | remove; as entregas na fila não saem mais |
| `GET /v1/webhooks/{id}/secret` | o segredo atual e, nas 24 horas da troca, o anterior |
| `POST /v1/webhooks/{id}/rotate-secret` | troca o segredo; o anterior vale 24 horas |
| `POST /v1/webhooks/{id}/test` | manda o evento `webhook.test` |
| `GET /v1/webhooks/{id}/deliveries` | as entregas, das mais novas para as mais antigas |
| `POST /v1/webhooks/{id}/deliveries/{deliveryId}/retry` | reenvia uma entrega agora |

## Criar

```bash theme={null}
curl https://api.westhetics.io/v1/webhooks \
  -H "Authorization: Bearer $WESTHETICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.exemplo.com/westhetics/clinica-aurora",
    "description": "Automação da recepção",
    "events": ["patient.created", "anamnesis.completed", "signature_request.completed"]
  }'
```

```json Resposta (201) theme={null}
{
  "data": {
    "id": "9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f",
    "integrationId": "6f1d2c3b-8a4e-4f7a-9c1d-2b3e4f5a6b7c",
    "url": "https://hooks.exemplo.com/westhetics/clinica-aurora",
    "description": "Automação da recepção",
    "events": ["anamnesis.completed", "patient.created", "signature_request.completed"],
    "status": "active",
    "disabledReason": null,
    "disabledAt": null,
    "failingSince": null,
    "lastDeliveryAt": null,
    "lastSuccessAt": null,
    "hasPreviousSecret": false,
    "previousSecretValidUntil": null,
    "deliveries": { "pending": 0, "failed": 0 },
    "createdAt": "2026-10-15T14:35:00Z",
    "updatedAt": "2026-10-15T14:35:00Z",
    "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw8ZqgF5u2F4M="
  }
}
```

* `events` aceita `["*"]` (todos os que o app pode ver, inclusive os que aparecerem no futuro) ou uma lista do [catálogo](https://docs.westhetics.io/webhooks/eventos.md). Sem `events`, ou com a lista vazia, vale `["*"]`.
* O endereço é guardado como o `fetch` o lê: o domínio em minúsculas, sem a porta 443 (`https://CRM.Exemplo.com:443/w` vira `https://crm.exemplo.com/w`).
* O segredo só vem nesta resposta e na de trocar o segredo. Repetir a chamada com a mesma `Idempotency-Key` devolve o webhook com `secret: null`: o segredo sai uma vez só. Depois, `GET /v1/webhooks/{id}/secret`.
* Até 5 webhooks por app; um endereço repetido no mesmo app responde `409`.

## Desativar sem remover

```bash theme={null}
curl -X PATCH https://api.westhetics.io/v1/webhooks/9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f \
  -H "Authorization: Bearer $WESTHETICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "disabled" }'
```

Reativar (`"status": "active"`) zera a contagem de falhas. Os eventos do período desativado não são entregues depois; leia-os em `GET /v1/events`.


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