> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP Monitor Configuration

> Configure DevHelm HTTP monitors — URL, method, headers, body, TLS, authentication, and timeouts

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

<Tip>
  **Define this in code.** [YAML format](/mac/yaml/monitors) · [Terraform](/mac/terraform/monitors)
</Tip>

## 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:

<CodeGroup>
  ```yaml devhelm.yml theme={null}
  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
  ```

  ```bash API theme={null}
  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"
        }
      }
    }'
  ```
</CodeGroup>

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:

```yaml theme={null}
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:

```yaml theme={null}
monitors:
  - name: Staging API
    type: HTTP
    config:
      url: https://staging.example.com/health
      method: GET
      verifyTls: false
```

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

## 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

1. Create a vault secret:

```bash theme={null}
devhelm secrets create --key API_TOKEN --value your-secret-value
```

2. Reference the secret in your monitor:

<CodeGroup>
  ```yaml devhelm.yml theme={null}
  monitors:
    - name: Authenticated API
      type: HTTP
      config:
        url: https://api.example.com/protected
        method: GET
      auth:
        type: bearer
        secret: API_TOKEN
  ```

  ```bash API theme={null}
  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>"
      }
    }'
  ```
</CodeGroup>

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](/platform/secrets) for vault management and the [authenticated endpoints guide](/guides/authenticated-endpoints) 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:

```yaml theme={null}
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](/incidents/policies) for full details.

## Next steps

<CardGroup cols={2}>
  <Card title="HTTP assertions" icon="check" href="/monitoring/http/assertions">
    All 11 assertion types with examples.
  </Card>

  <Card title="Authenticated endpoints" icon="lock" href="/guides/authenticated-endpoints">
    Patterns for monitoring private APIs.
  </Card>

  <Card title="Multi-region monitoring" icon="earth-americas" href="/guides/multi-region-monitoring">
    Reduce false positives with multi-region checks.
  </Card>

  <Card title="Incident policies" icon="triangle-exclamation" href="/incidents/policies">
    Trigger rules, confirmation, and recovery.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.