HTTP Monitor Configuration

HTTP monitors support a wide range of configuration options for request construction, TLS behavior, and authentication.

Define this in code. YAML format · Terraform

Required fields

Field	Type	Description
`name`	string (max 255)	Human-readable name for this monitor
`type`	string	Must be `HTTP`
`config.url`	string	Target URL to send requests to
`config.method`	string	HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`

Config fields

Field	Type	Default	Description
`config.url`	string	—	Target URL (required)
`config.method`	string	—	HTTP method (required)
`config.customHeaders`	object	`null`	Key-value map of extra headers to include
`config.requestBody`	string	`null`	Request body for POST, PUT, PATCH methods
`config.contentType`	string	`null`	Content-Type header for the request body
`config.verifyTls`	boolean	`true`	Whether to verify TLS certificates

Monitor-level fields

Field	Type	Default	Description
`frequencySeconds`	integer	`60`	Check frequency in seconds (30–86,400)
`enabled`	boolean	`true`	Whether the monitor is active
`regions`	array of string	all regions	Probe regions to run checks from
`environmentId`	UUID	`null`	Environment to associate with this monitor
`managedBy`	string	`API`	One of `API`, `DASHBOARD`, `CLI`, `TERRAFORM`, `MCP` (optional; surfaces set this automatically)

Custom headers

Add custom headers for API authentication, content negotiation, or any request metadata:

monitors:
  - name: API with headers
    type: HTTP
    config:
      url: https://api.example.com/data
      method: GET
      customHeaders:
        Accept: application/json
        X-Custom-Header: my-value

curl -X POST https://api.devhelm.io/api/v1/monitors \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API with headers",
    "type": "HTTP",
    "config": {
      "url": "https://api.example.com/data",
      "method": "GET",
      "customHeaders": {
        "Accept": "application/json",
        "X-Custom-Header": "my-value"
      }
    }
  }'

Custom headers aren’t settable via CLI flags — use YAML config-as-code or the API.

Request body

For POST, PUT, and PATCH methods, include a request body:

monitors:
  - name: POST endpoint
    type: HTTP
    config:
      url: https://api.example.com/submit
      method: POST
      contentType: application/json
      requestBody: '{"test": true}'

TLS verification

By default, HTTP monitors verify TLS certificates. Disable verification for self-signed certificates in staging environments:

monitors:
  - name: Staging API
    type: HTTP
    config:
      url: https://staging.example.com/health
      method: GET
      verifyTls: false

Disabling TLS verification means the monitor won’t detect certificate issues. Only disable this for internal or staging endpoints with self-signed certificates.

Authentication

HTTP monitors support four authentication methods via vault secrets. Credentials are stored encrypted and referenced by vaultSecretId.

Auth type	Header sent	Config fields
`bearer`	`Authorization: Bearer <secret>`	`vaultSecretId`
`basic`	`Authorization: Basic <base64>`	`vaultSecretId`
`header`	`<headerName>: <secret>`	`headerName`, `vaultSecretId`
`api_key`	`<headerName>: <secret>`	`headerName`, `vaultSecretId`

Setup

Create a vault secret:

devhelm secrets create --key API_TOKEN --value your-secret-value

Reference the secret in your monitor:

monitors:
  - name: Authenticated API
    type: HTTP
    config:
      url: https://api.example.com/protected
      method: GET
    auth:
      type: bearer
      secret: API_TOKEN

curl -X PUT https://api.devhelm.io/api/v1/monitors/<monitor-id>/auth \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "type": "bearer",
      "vaultSecretId": "<secret-uuid>"
    }
  }'

Monitor auth isn’t settable via CLI create flags — set it with the YAML auth: block or the monitor auth API (PUT /api/v1/monitors/{monitorId}/auth) on an existing monitor. See Secrets for vault management and the authenticated endpoints guide for patterns.

Incident policy

Every monitor has an incident policy. If you don’t specify one, the defaults apply:

Setting	Default
Trigger rule	2 consecutive failures per region → severity `down`
Confirmation	1 region failing, wait up to `max(60, frequency × 2)` seconds
Recovery	2 consecutive successes from 2 regions, 5-minute cooldown

Override the defaults:

monitors:
  - name: API Health
    type: HTTP
    config:
      url: https://api.example.com/health
      method: GET
    incidentPolicy:
      triggerRules:
        - type: consecutive_failures
          count: 3
          scope: per_region
          severity: down
      confirmation:
        type: multi_region
        minRegionsFailing: 2
        maxWaitSeconds: 120
      recovery:
        consecutiveSuccesses: 3
        minRegionsPassing: 2
        cooldownMinutes: 10

See Incident policies for full details.

Next steps

HTTP assertions

All 11 assertion types with examples.

Authenticated endpoints

Patterns for monitoring private APIs.

Multi-region monitoring

Reduce false positives with multi-region checks.

Incident policies

Trigger rules, confirmation, and recovery.

Getting Started

Monitoring as Code

Monitoring

Incidents

Alerting

Status Data

Platform

Common Patterns

HTTP Monitor Configuration

Required fields

Config fields

Monitor-level fields

Custom headers

Request body

TLS verification

Authentication

Setup

Incident policy

Next steps

HTTP assertions

Authenticated endpoints

Multi-region monitoring

Incident policies

​Required fields

​Config fields

​Monitor-level fields

​Custom headers

​Request body

​TLS verification

​Authentication

​Setup

​Incident policy

​Next steps

HTTP assertions

Authenticated endpoints

Multi-region monitoring

Incident policies

Required fields

Config fields

Monitor-level fields

Custom headers

Request body

TLS verification

Authentication

Setup

Incident policy

Next steps