Monitor API Health

O monitor API Health estende o monitor HTTP com a capacidade de fazer assertions em JSON Path — ou seja, você pode verificar não apenas se a API respondeu com 200, mas também se o conteúdo da resposta JSON contém o valor esperado.

⚠️

O monitor API Health requer o plano STARTER ou superior.

Como funciona

O worker executa os seguintes passos:

Faz a requisição HTTP para a URL configurada
Verifica o status code (igual ao monitor HTTP padrão)
Parseia o body da resposta como JSON
Navega até o campo definido em JSON Path
Compara o valor encontrado com o expectedValue configurado
Se os valores baterem → UP; se não baterem → DOWN

Configuração

JSON Path

O caminho até o campo que você quer verificar, usando notação de ponto.

Dado o seguinte response JSON:

{
  "data": {
    "status": "ok",
    "version": "2.1.0",
    "database": "connected"
  },
  "meta": {
    "uptime": 99.98
  }
}

JSON Path	Valor retornado
`data.status`	`"ok"`
`data.version`	`"2.1.0"`
`data.database`	`"connected"`
`meta.uptime`	`99.98`

expectedValue

O valor que você espera encontrar naquele caminho. A comparação é feita como string.

Exemplos:

"ok" — para verificar status
"connected" — para verificar conexão com banco
"2.1.0" — para verificar versão específica

A comparação entre o valor encontrado e o esperado é feita após conversão para string. O valor true (booleano) equivale à string "true".

Mensagem de erro

Quando o valor encontrado não bate com o esperado, o check é marcado como DOWN com uma mensagem descritiva:

JSON path "data.status" retornou "error", esperado "ok"

Se o JSON Path não existir na resposta:

JSON path "data.status" não encontrado na resposta

Se o body não for JSON válido:

Resposta não é um JSON válido

Exemplos de uso

Verificar endpoint de health check

Endpoint: GET https://api.suaempresa.com.br/health

Response:

{
  "status": "healthy",
  "db": "ok"
}

Configuração:

JSON Path: status
expectedValue: healthy

Verificar status de gateway de pagamento

Endpoint: GET https://api.gateway.com.br/v1/status

Response:

{
  "gateway": {
    "status": "operational",
    "latency_ms": 45
  }
}

Configuração:

JSON Path: gateway.status
expectedValue: operational

Validar versão da API

Endpoint: GET https://api.suaempresa.com.br/version

Response:

{
  "version": "3.0.0",
  "environment": "production"
}

Configuração:

JSON Path: environment
expectedValue: production

Isso garante que o ambiente correto está sendo servido — útil para detectar deployments acidentais em produção.

Monitorar resposta de serviço externo

Endpoint: GET https://api.parceiro.com.br/ping

Response:

{
  "pong": true
}

Configuração:

JSON Path: pong
expectedValue: true

Diferença entre API Health e HTTP simples

Recurso	HTTP	API Health
Verifica status code	Sim	Sim
Verifica keyword no body	Sim (texto)	Não
Verifica valor em JSON Path	Não	Sim
Plano necessário	FREE	STARTER+

Use HTTP com keyword quando quiser apenas confirmar presença de texto. Use API Health quando quiser validar um valor específico em um campo JSON.

Boas práticas

Aponte para um endpoint de health check dedicado Não use a API principal de negócio para monitoramento — crie um /health leve que retorna status de todos os subsistemas.

Monitore o campo mais crítico Se sua API depende de banco de dados e cache, verifique db.status e cache.status em monitores separados para saber exatamente qual subsistema falhou.

Cuidado com valores dinâmicos Não monitore campos como timestamps, contadores ou UUIDs — eles mudam a cada request e o monitor ficará sempre DOWN.

Próximos passos

HTTP / HTTPS TCP / Porta