HTTP monitors support a wide range of configuration options for request construction, TLS behavior, and authentication.
Required fields Field Type Description namestring (max 255) Human-readable name for this monitor typestring Must be HTTP config.urlstring Target URL to send requests to config.methodstring HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD
Config fields Field Type Default Description config.urlstring — Target URL (required) config.methodstring — HTTP method (required) config.customHeadersobject nullKey-value map of extra headers to include config.requestBodystring nullRequest body for POST, PUT, PATCH methods config.contentTypestring nullContent-Type header for the request body config.verifyTlsboolean trueWhether to verify TLS certificates
Monitor-level fields Field Type Default Description frequencySecondsinteger 60Check frequency in seconds (30–86,400) enabledboolean trueWhether the monitor is active regionsarray of string all regions Probe regions to run checks from environmentIdUUID nullEnvironment to associate with this monitor managedBystring — DASHBOARD, CLI, or TERRAFORM
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
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 bearerAuthorization: Bearer <secret>vaultSecretIdbasicAuthorization: Basic <base64>vaultSecretIdheader<headerName>: <secret>headerName, vaultSecretIdapi_key<headerName>: <secret>headerName, vaultSecretId
Setup
Create a vault secret:
devhelm secrets set API_TOKEN=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 vaultSecretId : <secret-uuid>
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.
