Custom JSON Health Check Responses in ASP.NET Core

When building modern APIs, health checks are a common way to expose the status of your application. By default, ASP.NET Core health checks return a very minimal response (often just HTTP status codes). But what if you want to return a clean JSON payload that can easily be consumed by monitoring systems?

Step 1: Create a Custom JSON Response Writer

ASP.NET Core’s HealthCheckOptions allows us to plug in a custom ResponseWriter. Here’s one that outputs a JSON response containing the health status:

private async Task JsonResponseWriter(HttpContext context, HealthReport report)
{
    context.Response.ContentType = "application/json";
    await JsonSerializer.SerializeAsync(
        context.Response.Body,
        new { Status = report.Status.ToString() },
        new JsonSerializerOptions 
        { 
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase 
        }
    );
}

What this does:

• Sets the response type to application/json.

• Serializes an anonymous object containing the health check Status.

• Uses camelCase naming to keep JSON consistent with API conventions.

---

Step 2: Hook the Writer into Health Checks

Now, wire up the health check middleware in your pipeline:

app.UseHealthChecks("/health", new HealthCheckOptions 
{ 
    ResponseWriter = JsonResponseWriter 
});

Explanation:

• Requests to /health will trigger your health checks.

• Instead of the default plain-text response, your JsonResponseWriter will return JSON like:

{
  "status": "Healthy"
}

---

Step 3: Configure Global JSON Options

To keep your entire API’s JSON responses consistent, configure the JsonSerializerOptions in Startup.cs (or Program.cs for minimal hosting):

services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.IgnoreNullValues = true;
        options.JsonSerializerOptions.WriteIndented = true;
    });

• IgnoreNullValues = true → Null properties won’t clutter your responses.

• WriteIndented = true → JSON output is more readable (great for debugging).

With this setup:

• Hitting /health gives a clean JSON response.

• All controllers return JSON using consistent formatting.

• Monitoring tools can easily parse your app’s health status.

Example response:

{
  "status": "Healthy"
}

---

Conclusion

By adding a custom ResponseWriter and configuring global JSON options, you can make your ASP.NET Core health checks more API-friendly. This approach is simple, clean, and integrates seamlessly into modern monitoring setups like Kubernetes, Prometheus, or cloud load balancers.