Configure and use HTTP/HTTPS monitoring for websites, APIs, and web endpoints including authentication, custom headers, and POST data.

HTTP Monitoring

HTTP monitoring in UptimeHunt provides comprehensive website and API endpoint monitoring capabilities. This guide covers configuration, authentication, advanced features, and best practices for HTTP/HTTPS monitoring.

Basic Configuration

Required Parameters

Service Name — Descriptive identifier for the monitoring service. Example: "Production API Health Check".

URL — Complete endpoint URL including protocol. Format: https://example.com/path. Supports both HTTP and HTTPS. Maximum length: 4096 characters.

HTTP Method — Request method to use for checks. Options: GET, POST, HEAD. Default: GET.

Optional Parameters

Project — Project assignment for organization.

Enabled — Toggle to activate/deactivate monitoring.

Check Interval — Monitoring frequency in seconds. Default: 180 s (3 min). Minimum is plan-dependent (Free: 300 s, Pro: 60 s, Team: 30 s, Scale: 30 s, Enterprise: 30 s — 30 s is the platform-wide floor).

HTTP Methods

GET

Standard method for retrieving resources.

Use Cases:

Website homepage monitoring
API endpoint availability
Health check endpoints
Status pages

Configuration:

No request body required
Can include custom headers
Supports authentication

POST

Method for sending data to endpoints.

Use Cases:

API endpoint testing with data
Login endpoint validation
Form submission monitoring
Data processing endpoints

Configuration:

Requires request body data
Supports JSON, XML, form data
Can include custom headers
Supports authentication

HEAD

Lightweight method requesting only headers.

Use Cases:

Quick availability checks
Metadata verification
Reduced bandwidth monitoring
Response header validation

Configuration:

No response body retrieved
Faster than GET
Limited validation options

Authentication

UptimeHunt supports multiple authentication methods for protected endpoints.

No Authentication

Default setting for public endpoints.

Configuration:

Select "None" from authentication dropdown
No additional parameters required

Use When:

Monitoring public websites
Accessing open APIs
Checking unauthenticated endpoints

Basic Authentication

HTTP Basic Authentication using username and password.

Configuration:

Select "Basic" from authentication dropdown
Enter Username
Enter Password

Technical Details:

Credentials sent in Authorization header
Base64 encoded username:password
Supported by most web servers
Standard HTTP authentication method

Example Use Cases:

Admin panels with basic auth
Development/staging environments
Legacy systems
Simple authentication requirements

Security Considerations:

Always use HTTPS with Basic Auth
Credentials transmitted with every request
Create dedicated monitoring credentials
Limit credential permissions

Bearer Token

Token-based authentication for modern APIs.

Configuration:

Select "Bearer Token" from authentication dropdown
Enter your Bearer Token

Technical Details:

Token sent in Authorization header
Format: Authorization: Bearer <token>
Common in RESTful APIs
JWT token support

Example Use Cases:

Modern REST APIs
Microservices
OAuth 2.0 protected resources
JWT-authenticated endpoints

Security Considerations:

Tokens may expire (plan for rotation)
Use HTTPS to protect tokens
Generate dedicated monitoring tokens
Limit token permissions/scopes

Custom Headers

Add custom HTTP headers to requests for specialized monitoring scenarios.

Adding Headers

In service configuration, locate Headers section
Click "Add Header" button
Enter Header Name (e.g., Accept)
Enter Header Value (e.g., application/json)
Repeat for additional headers

Common Headers

Content-Type

Name: Content-Type
Value: application/json

Specifies request body format for POST requests.

Accept

Name: Accept
Value: application/json

Indicates expected response format.

User-Agent

Name: User-Agent
Value: UptimeHunt-Monitor/1.0

Identifies the monitoring client.

API-Key

Name: API-Key
Value: your-api-key-here

Custom API key authentication.

X-Custom-Header

Name: X-Custom-Header
Value: custom-value

Application-specific headers.

Header Limitations

Maximum header name length: 64 characters
Maximum header value length: 4096 characters
No limit on number of headers (reasonable use)

Use Cases

API Version Selection

Name: API-Version
Value: v2

Content Negotiation

Name: Accept-Language
Value: en-US

Custom Authentication

Name: X-API-Token
Value: token-value

Correlation Tracking

Name: X-Request-ID
Value: monitoring-check-id

POST Data

For POST requests, configure the request body.

Text Input

Enter request body directly in the form field.

Supported Formats:

JSON
XML
Form-urlencoded
Plain text

JSON Example:

{
  "username": "monitor",
  "password": "check123"
}

XML Example:

<?xml version="1.0"?>
<check>
  <status>request</status>
</check>

Form Data Example:

username=monitor&password=check123

File Upload

Upload a file containing the request body.

Use Cases:

Large request bodies
Complex JSON/XML structures
Binary data
Reusable request templates

Process:

Prepare request body in a file
Click file upload button
Select file from your computer
File content used as POST body

File Limitations

Uploaded files should be reasonable in size. Extremely large payloads may cause timeout or performance issues.

Content-Type Header

Always set appropriate Content-Type header for POST data:

For JSON:

Content-Type: application/json

For XML:

Content-Type: application/xml

For Form Data:

Content-Type: application/x-www-form-urlencoded

IP Address Family

Control which Internet Protocol versions the prober uses to connect to your HTTP endpoint.

Address Family Options

Auto (Default)

The prober resolves the hostname and dials using the operating system's default behavior (CURL_IPRESOLVE_WHATEVER). No per-family result breakdown is reported.

Use When:

No specific IPv4/IPv6 requirement
Target has both IPv4 and IPv6 support
Backward compatibility preferred

IPv4 Only

The prober forces IPv4 resolution only. DNS is checked for an A record; if no A record exists, the check fails with a no_record error (distinct from dns or timeout).

Use When:

IPv6 is not available or disabled
Specific IPv4 testing required
Legacy infrastructure

IPv6 Only

The prober forces IPv6 resolution only. DNS is checked for an AAAA record; if no AAAA record exists, the check fails with a no_record error.

Use When:

Testing IPv6 deployment
IPv4 has been deprecated
Specific IPv6 infrastructure

Both IPv4 and IPv6

The prober dials both IPv4 AND IPv6 independently and reports separate metrics for each family under response.families.ipv4 and response.families.ipv6. The overall check succeeds only if BOTH families are reachable (AND rule). The top-level response.time_ms always deterministically mirrors the IPv4 (primary) family — it is never a race for whichever family answered first.

Use When:

Rolling out IPv6 (AAAA records)
Monitoring dual-stack deployments
Detecting per-family issues independently

Both-Mode Details

In "both" mode, each family reports its own result object under response.families.<family> (<family> is ipv4 or ipv6):

Per-Family Fields

response.families.<family>.reachable — whether that family connected successfully
response.families.<family>.time_ms — that family's response time in milliseconds (a flat number)
response.families.<family>.ip — the IP address that family resolved and dialed
response.families.<family>.error — error detail when that family failed; absent/null on success

There is no per-family HTTP status field — response.families.<family>.status does not exist. Status-code assertions read only the top-level response.http_status_code, which reflects the primary (IPv4) family's response.

Per-Family Assertions

Configure assertions against either family independently:

Assertion type	Result path
`ipv4_reachable`	`response.families.ipv4.reachable`
`ipv6_reachable`	`response.families.ipv6.reachable`
`ipv4_response_time_ms`	`response.families.ipv4.time_ms`
`ipv6_response_time_ms`	`response.families.ipv6.time_ms`
`ipv4_address`	`response.families.ipv4.ip`
`ipv6_address`	`response.families.ipv6.ip`

Assertion family must be covered by the address family setting

A per-family assertion is only valid when the service's address family setting covers that family: ipv4_* assertions need ipv4 or both; ipv6_* assertions need ipv6 or both. Saving an assertion for an uncovered family (e.g. ipv6_reachable on a service set to auto or ipv4) is rejected with a 400.

Both mode doubles the work, not the interval

Families are dialed sequentially, each allotted the full configured timeout — worst case, a "both" check can take up to 2× the timeout to complete. Keep this in mind before setting a short check interval. The full request also runs once per family per cycle: an endpoint monitored with a POST body receives that body twice per cycle — once for IPv4, once for IPv6.

Example Scenario: AAAA Rollout

When rolling out IPv6 (AAAA DNS record), use "both" mode to detect IPv6-specific issues without alarming IPv4 users:

Create a duplicate HTTP check with address family set to "IPv6 Only"
Configure alerts only on the IPv6 check
As IPv6 stabilizes, migrate the main check to "Both" mode
Now both families are monitored, but you have visibility into per-family problems:
- IPv4 slow? — Only the IPv4 family fails
- IPv6 unreachable? — Only the IPv6 family fails
- Both healthy? — Green across the board

This avoids cascading alert fatigue during infrastructure transitions.

Transport & TLS

Fine-grained control over the per-check timeout, redirect handling, and TLS certificate verification. These are enforced end-to-end by the prober — earlier prober builds accepted redirect/TLS settings but silently ignored them; a current-build prober actually dials with them.

In the UI, redirect-following and TLS verification live in the Connection group, in the request's own settings section — directly below the URL/POST-data fields, above Advanced Settings, and separate from the assertion rules (see Connection); the timeout override lives separately, under Advanced Settings.

Request Timeout

timeout — optional per-check override, in whole seconds, 1–120. When omitted, the check uses the platform's own default (currently ~10 seconds).
Applies to the complete request/response cycle — DNS resolution, connection, TLS handshake, and data transfer all count against it.
In the UI, this field lives under Advanced Settings in the service's HTTP/HTTPS settings section; see the timeout field on the Services API for the exact request/response shape.

Redirects

follow_redirects — whether the prober follows HTTP redirects. Default: true.
max_redirects — maximum number of hops to follow. Default: 5.
Every redirect hop is independently re-validated against the SSRF/target guard and re-pins the resolved IP before it's dialed, so a redirect can never smuggle a check past the guard to a private network or a cloud-metadata address the original URL wasn't allowed to reach.
A 303 response, or a 301/302 in reply to a POST, downgrades the follow-up request to GET (matching curl/browser convention); 307/308 preserve the original method and body.
Exhausting max_redirects without reaching a final response fails the check with error.kind: protocol.
The reported response.time_ms covers the entire redirect chain, not just the final hop.

TLS Verification

verify_tls — whether the prober verifies the TLS certificate chain and hostname on an HTTPS check. Default: true for newly created services.
With verify_tls: true (the default), an expired, self-signed, or hostname-mismatched certificate fails the check.
With verify_tls: false, the prober connects without validating the certificate — useful for staging/internal endpoints whose certificate you can't otherwise fix, but a real MITM or a genuinely expired certificate then goes undetected. Prefer the automatic TLS-expiry assertion below over disabling verification outright.
A TLS-specific failure (handshake failure, chain/hostname validation failure, expired or untrusted certificate) is reported with its own error.kind: tls — distinct from dns, connection, timeout, protocol, and no_record — so a certificate problem is distinguishable from an ordinary outage in alerts and result history.

Automatic TLS-Expiry Assertion

Set tls_expiry_min_days to a positive number of days and UptimeHunt automatically adds this assertion to the service's expectations — no need to hand-configure it:

{ "type": "tls_expiry_days", "op": "gte", "value": 30, "severity": "degraded" }

The auto-injected assertion always carries severity: degraded — an expiring certificate warns without opening a full "down" incident.
tls_expiry_days remains configurable manually as an ordinary assertion too (for example with severity: down, or a different threshold) — the two are independent and both can be present at once.
tls_expiry_min_days only affects what's evaluated; it never changes what the prober dials, and has no effect on follow_redirects/max_redirects/verify_tls.
Three sibling TLS assertions are also available as ordinary rules: tls_valid_for_host (the certificate covers a given hostname), tls_chain_valid (the chain verifies against a trusted root), and tls_issuer (the issuing CA's organization name). All four are grouped in the rules builder as one "TLS certificate" subject — see TLS Certificate.

Automatic Retry on Transient Failures

A scheduled check (as opposed to an on-demand "Run Now") that fails at the transport level — timeout, connection refused, DNS failure, TLS failure — is retried once, a couple of seconds later, before it is recorded as down. Only the final attempt's outcome counts toward uptime history and alerting; the retry is never scored as a second, independent check.

On-demand runs ("Run Now" from the dashboard or the API) are never retried — an on-demand run is asking "is it up right now", not requesting a delayed confirmation.
A check refused by the SSRF/target guard is never retried either — that refusal is deterministic, not a transient network condition, so retrying it cannot produce a different outcome.
The retry only happens when the check's interval leaves enough room for it (at least 3× the effective timeout); on a very short interval, a failing check is recorded on the first attempt.
The check result carries an additive retry object recording what happened: {"attempted": 1, "first_error_kind": null} means no retry was needed, and {"attempted": 2, "first_error_kind": "timeout"} means the first attempt failed with the given error kind before a second attempt produced the recorded result.

Response Validation

HTTP checks are validated against expectations — the same Expected results rules builder documented in Services Management. This section covers the subjects and operators specific to HTTP; the mechanics of the builder itself (rows, the default/edited tag, severities) live there.

Status Code Checking

The HTTP status subject supports is one of, is not one of, is in range, equals, at least, at most, under, and over. is one of/is not one of open a chip picker mixing whole status classes — 1xx–5xx, each covering its hundred-range — with specific 3-digit codes, so "any 2xx, 3xx, or 429" is one rule. is in range takes an inclusive min/max code; equals takes a single code; at least/at most/under/over each compare against a single numeric code — exactly the operators the two built-in default rows below are built from.

New HTTP services start with two built-in rows: status at least 200 and status under 400, both Down — together "any 2xx or 3xx":

Typically healthy:

2xx codes (200, 201, 204, etc.)
3xx codes (301, 302, 304, etc.)

Typically unhealthy (add rules to flag explicitly, or rely on the default range):

4xx codes (400, 401, 403, 404, etc.)
5xx codes (500, 502, 503, 504, etc.)
Connection errors and timeouts always mark the check unreachable, independent of any status-code rule.

Response Body and Regular Expressions

The Response body subject supports contains, does not contain, matches regex, does not match regex, is, is one of, is not one of, and exists. A regex pattern is bounded for safety before it's ever evaluated: up to 200 characters, rejected at save time for a known catastrophic shape (a nested repeating group like (a+)+, or a repeated group with overlapping branches like (a|a)+ — a disjoint alternation like (GET|POST)+ is fine), and matched at evaluation time against only the first 8 KiB of the body under a 0.5-second budget. A pattern that can't be safely evaluated (timeout, or no match within that 8 KiB prefix of a larger body) is inconclusive — it never fails the rule and can never open a false incident on its own.

Response Time

The Response time subject supports under, over, is, is one of, is not one of, at least, at most, and is in range, in milliseconds:

Time from request initiation to full response
Measured in milliseconds
Timeout: Configurable (default: 10 seconds) — see Timeout Configuration
Historical data available

TLS Certificate

One combined TLS certificate subject groups four checks — valid for at least N days, is valid for host, chain is valid, issuer contains — described in full in TLS certificate. Only chain is valid depends on Verify TLS certificate being on (see Connection); with it off, that one assertion evaluates to no verdict (skipped). The other three — expiry, host, and issuer — read facts the prober captures on every HTTPS hop regardless of verify_tls, so they still evaluate against whatever certificate is presented, even an untrusted or self-signed one, and can genuinely fail and open a real incident. See also Automatic TLS-Expiry Assertion for the standalone tls_expiry_min_days shortcut.

Connection Validation

A check is marked reachable when:

DNS resolution succeeds
TCP connection is established
TLS/SSL handshake completes (HTTPS)
An HTTP response is received

Failure at any of these steps marks the check unreachable regardless of any Expected results rule — rules only apply once a response actually arrives.

Advanced Configuration Examples

Monitoring Authenticated API

Name: Production API Health
URL: https://api.example.com/v1/health
Method: GET
Authentication: Bearer Token
Token: eyJhbGciOiJIUzI1NiIs...
Headers:
  - Accept: application/json
Interval: 3 minutes

Name: User Login Test
URL: https://app.example.com/api/login
Method: POST
Authentication: None
Headers:
  - Content-Type: application/json
POST Data: {"email":"test@example.com","password":"test123"}
Interval: 5 minutes

Monitoring with Custom Headers

Name: Versioned API Endpoint
URL: https://api.example.com/users
Method: GET
Authentication: Basic
Username: apiuser
Password: ********
Headers:
  - API-Version: v2
  - Accept: application/json
  - X-Client-ID: monitoring
Interval: 3 minutes

SSL/TLS Considerations

HTTPS Monitoring

For HTTPS endpoints:

SSL/TLS certificate validation performed by default (verify_tls: true) — see Transport & TLS to disable it for a specific check, or to add an automatic TLS-expiry assertion instead
Expired certificates cause check failures
Self-signed certificates may fail validation
Certificate failures are reported with a distinct error.kind: tls

Best Practices

Use HTTPS for all production monitoring
Ensure certificates are valid and current
Monitor certificate expiration separately
Use trusted certificate authorities

Timeout Configuration

Default Timeout

Default timeout: ~10 seconds
Applies to complete request/response cycle
Includes DNS, connection, and data transfer

Per-Check Override

Set timeout (1–120 seconds) on an individual service to override the platform default for that check only — see Transport & TLS.
Leave it unset to keep using the platform default; a per-check override is optional, not required.
Your organization's plan may cap the maximum below the absolute 120 s: Free 10 s, Pro 30 s, Team 30 s, Scale 45 s, Enterprise 60 s. The Timeout field states and enforces your plan's actual ceiling — see Request Timeout for the full behavior, including how a pre-existing over-cap value is grandfathered.