Health Check Endpoint Design for Web Apps

Load balancers, container platforms and monitoring tools all need a quick way to ask an application, "are you working?" The usual answer is a health check endpoint: a small URL that returns success when the application is healthy and an error when it is not. It sounds trivial, but poorly designed health checks cause real outages. A check that tests too little lets broken instances keep receiving traffic; a check that tests too much can make every instance look unhealthy when one shared dependency slows down, triggering restarts that make things worse. This guide explains how to design liveness and readiness checks, what each should test, how platforms use them and which mistakes to avoid.

What a health check endpoint does

A health check endpoint is a route, such as /health or /ready, that returns a status code and sometimes a short body describing the application's state. Other systems call it regularly:

• Load balancers use it to decide whether to send traffic to an instance
• Container orchestrators use it to decide whether to restart a container or route traffic to it
• Monitoring tools use it to alert when an application is down
• Deployment tools use it to decide whether a new version is ready

Because different callers act differently on the result, one check rarely fits every purpose.

Liveness versus readiness

Kubernetes, for example, distinguishes several probe types. Its documentation explains that liveness probes determine when to restart a container, for instance to catch a deadlock where an application is running but unable to make progress, while readiness probes determine when a container is ready to accept traffic (Kubernetes: Liveness, Readiness, and Startup Probes). A startup probe can also be used for applications that take time to start.

The same idea applies outside Kubernetes:

• Liveness: is this process fundamentally broken and in need of a restart?
• Readiness: should this instance receive traffic right now?

Keeping these separate is the most important design decision, because the actions taken on failure are so different.

What a liveness check should test

A liveness check should be simple and depend only on the process itself. It should answer whether the application can still respond at all. Avoid checking databases, external APIs or other services in a liveness check. If a shared database slows down, every instance's liveness check could fail, the platform could restart all of them, and the application would be down even after the database recovers.

What a readiness check should test

A readiness check can include dependencies the instance needs to serve requests, such as:

• Configuration loaded and initial set-up complete
• Connection to the primary database available
• Required caches warmed, if the application cannot work without them

When readiness fails, the instance stops receiving traffic but is not restarted, giving it time to recover. Be selective: include only dependencies without which the instance genuinely cannot serve useful responses.

Treat optional dependencies differently

Many dependencies are optional for some features. If an email service or recommendation engine is unavailable, the application can often still serve most requests. Do not fail readiness for optional dependencies; instead, degrade the affected features and report the issue to monitoring separately. Our guide to graceful degradation explains how to keep core functions working when parts of a system fail.

Keep checks fast and cheap

Health checks run frequently on every instance. They should:

• Respond quickly, well within the caller's timeout
• Avoid heavy queries; a simple connection check or lightweight query is usually enough
• Use short timeouts for any dependency checks
• Avoid writing data or triggering side effects

A slow health check can cause false failures under load, exactly when stability matters most.

Worked example: health check endpoint design

The table below shows a hypothetical design for a web application with a database, a cache and an email service. Paths, checks and responses are illustrative.

EndpointUsed byChecksReturns failure whenPlatform action on failure/livezContainer orchestrator liveness probeProcess can handle a requestProcess is stuck or unresponsiveRestart container/readyzLoad balancer and readiness probeStart-up complete; database connection availableStill starting, or cannot reach databaseStop sending traffic to this instance/health/detailsMonitoring and on-call staffDatabase, cache, email service and queue depth, each with status and timingNever fails the instance; reports degraded componentsAlert team if a component is degraded

The detailed endpoint gives people useful information without affecting traffic decisions, and it should be protected so it does not expose internal details publicly.

Handle shutdowns cleanly

Health checks also matter when instances stop. During a deployment or scale-down, an instance should first fail its readiness check so the load balancer stops sending new traffic, then finish requests already in progress, and only then shut down. Without this, users may see errors during every release. Check how your platform signals shutdown and make sure the application responds by draining traffic gracefully.

Protect detailed health information

Detailed health output can reveal versions, hostnames and dependency names useful to attackers. Keep public checks minimal, returning only a status, and restrict detailed endpoints to internal networks or authenticated users.

Tune probe timing

Platforms let you configure how often checks run, how long to wait for a response and how many failures trigger action. Settings that are too aggressive cause restarts during brief slowdowns; settings that are too relaxed leave broken instances serving traffic. Base them on observed behaviour, and give slow-starting applications enough time before liveness checks begin.

Avoid common mistakes

• Using the same endpoint for liveness and readiness
• Checking shared dependencies in liveness checks, causing mass restarts
• Health checks that perform heavy queries or writes
• Returning success while the application cannot actually serve requests
• Exposing detailed internal information publicly
• Never testing what happens when a dependency fails

Test failure scenarios

In a test environment, simulate a stuck process, a database outage and an optional service failure, and confirm the platform behaves as intended: restarting stuck processes, routing traffic away from instances that cannot serve and keeping the application available when optional services fail. Our guide to high availability architecture covers how health checks fit into wider resilience design.

Monitor health over time

Record health check results and response times. Rising check latency, frequent readiness flapping or repeated restarts are early warnings of problems such as resource exhaustion or unstable dependencies.

Frequently Asked Questions

What is a health check endpoint?

It is a URL that load balancers, orchestrators and monitoring tools call to learn whether an application instance is working and ready to receive traffic.

What is the difference between liveness and readiness checks?

Liveness determines whether a process needs restarting. Readiness determines whether an instance should receive traffic right now.

Should health checks test the database?

Readiness checks can test a required database connection. Liveness checks should not, because a shared database problem could trigger restarts of every instance.

How fast should a health check respond?

Quickly and well within the caller's timeout, using lightweight checks with short dependency timeouts and no side effects.

Build applications that report their health well

We design health checks, probes and monitoring that keep traffic flowing to healthy instances and avoid restart storms. See our custom app development services, or talk to us about health check design.

About the Author

Manav Sharma is the founder of Insyrge and a CRM solutions architect. He works across Zoho, Salesforce, HubSpot, Odoo and more, designing the CRM setups, integrations and automations that keep sales and operations teams working from the same data.