Skip to main content

​
Why Add a Health Check?

Adding a Health Check helps:
  • Detect downtime or broken connections early
  • Prevent user frustration when the API is offline
  • Give your Agent clear fallback behavior when the service is unavailable
A Health Check is like a “heartbeat” that confirms your Action’s backend is alive and responding.

​
How It Works

When you provide a Health Check URL, Watermelon pings that endpoint to make sure it returns a valid 200 OK response. If the endpoint returns an error (for example 500 or 404), or doesn’t respond at all, the check fails. When that happens, your Agent will follow the instruction you define under “Provide an instruction”.

​
Setting Up a Health Check

1

Go to actions

Go to your AI Agent → Actions.
2

Open the Action you want to add a health check to.

Scroll down to the Health check section (see screenshot)
Health Check Pn
3

Fill in the health check URL

Enter a lightweight API endpoint that reliably returns a 200 OK status when the system is healthy.Examples:
  • /health
  • /status
  • /ping
Example URL:
https://api.example.com/v1/health
The endpoint should:
  • Use HTTPS
  • Require minimal or no authentication
  • Return a fast, small response (ideally under 1 second)
4

Provide an Instruction

This tells your AI Agent what to do if the health check fails — for example, what to tell the user or how to proceed.Example instructions:
“If this API is unavailable, tell the user: ‘I can’t reach the system right now, please try again later.’” “When the health check fails, stop all actions and ask the user to retry after a few minutes.” “If the system is down, provide a polite fallback message instead of continuing the Action.”
Your Agent will automatically follow this instruction whenever the API connection fails.

​
What a Valid Health Check Response Looks Like

A healthy endpoint should return: 
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "healthy"
}
Unhealthy responses include:
  • 401 Unauthorized → Invalid credentials
  • 404 Not Found → Wrong URL
  • 500 Internal Server Error → Server issue
  • Timeout → API unreachable
If Watermelon detects one of these, it executes your fallback instruction.