Skip to main content

Health Checks with OhDear

This document describes how Farfalla exposes operational health checks and how OhDear monitors them for automated alerting.

How it works​

OhDear polls a dedicated health endpoint and raises alerts when any check reports a failure.

  • Endpoint: /health-check-results
  • Authentication: secret header to prevent unauthorized access
  • Response: consistent JSON payload with per-check status and metadata
  • Schedule: OhDear runs the checks every 5 minutes (configurable in OhDear)

Why We Use Health Checks​

Health checks monitor critical business logic that might fail silently. These checks help us catch issues before they impact users or revenue.

Configuration​

Environment Variables​

Add these to your .env file:

# Enable the OhDear health check endpoint
OH_DEAR_HEALTH_CHECK_ENABLED=true

# Generate a secure secret for authentication
OH_DEAR_HEALTH_CHECK_SECRET=your_secret_here_use_openssl_rand_base64_32

OhDear Dashboard Setup​

  1. Login to OhDear dashboard
  2. Navigate to your application
  3. Go to Application Health settings
  4. Add endpoint:
    • URL: https://api.publica.la/health-check-results
    • Secret: (paste the secret from the .env)
  5. Save

OhDear will now monitor your health checks every 5 minutes.

Endpoint​

Once configured, the endpoint is available at:

GET /health-check-results

Authentication: Requires the oh-dear-health-check-secret header with your secret.

Example request:

curl -H "oh-dear-health-check-secret: your_secret_here" \
     https://api.publica.la/health-check-results

Example response:

{
  "finishedAt": "2025-10-03T15:00:00.000000Z",
  "checkResults": [
    {
      "name": "Check Name",
      "label": "Check Label",
      "notificationMessage": "Check notification message",
      "shortSummary": "Short summary",
      "status": "ok",
      "meta": {}
    }
  ]
}

Adding New Health Checks​

Health checks are organized by domain. Each domain can have its own HealthChecks/ directory containing checks relevant to that domain's business logic.

To add a new health check:

  1. Create a check class under the appropriate domain directory (e.g., app/Domains/Commerce/HealthChecks/)
  2. Register the check in app/Providers/HealthCheckServiceProvider.php with a clear name and label
  3. Add feature tests in tests/Feature/HealthChecks/
  4. Deploy and verify using php artisan health:check

Resources​

X

Graph View