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