External Healthcheck

Overview

Helix Spring Boot webservice that demonstrates the external healthcheck endpoints and how a custom health provider

contributes to both internal and external health.

Run this example from the shared examples build:

./gradlew -p examples runExample -Pexample=rest-api/external-healthcheck --init-script "$(pwd)/helix.init.gradle"

What It Shows

• enabling Helix external health checks with management.endpoint.externalhealth.enabled=true
• a custom Spring HealthIndicator bean named partnerApi
• the difference between internal actuator health and external health
• the external /health endpoint returning only UP or DOWN
• the external /liveness endpoint always returning UP
• internal actuator health exposing component details, including the custom contributor

Endpoints

• GET /v1/external-healthcheck/comparison
• GET /health
• GET /liveness
• GET /health on the management port

Example comparison response

{
  "request_id": "generated-by-helix",
  "status": "SUCCESS",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "application": "external-healthcheck",
    "externalHealthUrl": "http://localhost:8080/health",
    "livenessUrl": "http://localhost:8080/liveness",
    "internalHealthUrl": "http://localhost:8081/health",
    "customContributorName": "partnerApi",
    "partnerApiConfiguredHealthy": true
  }
}

Example internal health response excerpt

{
  "status": "UP",
  "components": {
    "partnerApi": {
      "status": "UP",
      "details": {
        "provider": "partner-api",
        "region": "us-east"
      }
    }
  }
}

Example external health response

{
  "status": "UP"
}

Development

Building the Application

Run the following command to build the service:

./gradlew clean build

Testing the Application

Run the following command to run the service tests:

./gradlew test
./gradlew integration

Trying the API

Run the service:

Then compare the endpoints:

You can also start the example with the custom provider down:

./gradlew bootRun

curl http://localhost:8080/v1/external-healthcheck/comparison

curl http://localhost:8080/health

curl http://localhost:8080/liveness

curl http://localhost:8081/health

./gradlew bootRun --args='--demo.partner-api.healthy=false'