Headers

Configure custom HTTP headers to send with your test requests. Headers allow you to customize how your API monitoring requests behave, authenticate with APIs, and simulate different client scenarios.

Adding Headers

Click Headers to expand the headers section, then add key-value pairs:

Header	Value
Accept	application/json
X-API-Key	sk_live_51HZj2jK...
X-Request-Source	monitoring

Headers you configure are sent with every test execution across all regions.

Common Use Cases

1. Content-Type & Accept Headers

When to use: Telling the API what format you're sending and expecting back

Content-Type: application/json
Accept: application/json

Required for requests with a body (POST, PUT, PATCH). Common values:

• application/json - JSON data (most REST APIs)
• application/x-www-form-urlencoded - Form submissions
• text/xml or application/xml - XML data
• multipart/form-data - File uploads

2. API Keys & Custom Authentication

When to use: APIs that require authentication via custom headers

X-API-Key: sk_live_51HZj2jK...
X-Custom-Auth: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example: Monitoring third-party APIs (Stripe, Twilio, SendGrid)

• Many SaaS APIs require a secret key in a custom header
• Each monitoring request includes your API key to authenticate

Note: For standard Bearer token or Basic auth, use the dedicated Authentication section instead - it provides secure credential storage and OAuth2 token refresh.

3. API Versioning

When to use: Testing specific API versions

Accept-Version: v2
API-Version: 2023-10-15
X-API-Version: 3.0

Example: Your API uses header-based versioning

• Different endpoints behave differently based on version
• Ensures you're testing the correct API version
• Prevents unexpected changes when new versions are released

4. Request Tracking & Correlation

When to use: Identifying monitoring requests in your API logs

X-Request-ID: monitor-{{uuid}}
X-Correlation-ID: pingward-{{timestamp}}
User-Agent: Pingward-Monitor/1.0
X-Request-Source: monitoring

Example: Distinguishing monitoring traffic from real user traffic

• Your API logs every request
• These headers help you filter out monitoring requests from analytics
• The variable creates a unique ID for each test execution
• Useful for debugging and tracing requests through distributed systems

5. Cache Control

When to use: Ensuring you get fresh data, not cached responses

Cache-Control: no-cache
Pragma: no-cache

Example: Testing actual API behavior, not CDN cache

• Bypasses intermediate caches (CDN, reverse proxy)
• Ensures monitoring hits the real backend
• Critical for detecting backend issues that might be masked by caching

6. Feature Flags & Experiments

When to use: Testing specific features or A/B test variants

X-Feature-Flags: new-checkout:enabled,beta-ui:disabled
X-Experiment: variant-b
X-Beta-Features: true

Example: Your API uses feature flags for gradual rollouts

• Monitor different code paths without deploying separate endpoints
• Test new features before they're available to all users
• Verify that beta features work correctly

7. Multi-Tenant & Organization Context

When to use: APIs that serve multiple tenants/organizations

X-Tenant-ID: acme-corp
X-Organization: 12345
X-Account-ID: org_abc123

Example: Testing tenant-specific behavior

• Your API returns different data per tenant
• Monitor that tenant isolation works correctly
• Verify tenant-specific configurations

8. Geographic & Regional Headers

When to use: Testing region-specific behavior

CloudFront-Viewer-Country: US
X-Geo-Location: EU
Accept-Language: en-US,en;q=0.9

Example: Your API returns different content by region

• Simulate requests from specific countries
• Test GDPR compliance for EU users
• Verify geo-blocking rules

9. Client Identification

When to use: Simulating different client types (mobile, web, etc.)

X-Client-ID: mobile-ios
X-App-Version: 3.2.1
X-Platform: ios

Example: Your API has different behavior for mobile vs web

• Test mobile-specific endpoints
• Verify version compatibility
• Monitor client-specific rate limits

10. Security Headers

When to use: Testing CSRF protection or security requirements

X-CSRF-Token: {{csrf_token}}
X-Security-Token: monitoring-bypass
Origin: https://app.example.com

Example: Your POST endpoints require CSRF tokens

• Monitor the complete authentication flow
• Verify security mechanisms work correctly
• Test cross-origin request handling

Header Variables

Dynamic values are supported in header values using the syntax:

Variable	Description	Example Value
	Current Unix timestamp	1707404045
	Current date (YYYY-MM-DD)	2024-02-08
	Random UUID v4	550e8400-e29b-41d4-a716-446655440000

Example:

X-Request-ID: monitor-{{uuid}}
X-Timestamp: {{timestamp}}
X-Date: {{date}}

Variables are generated fresh for each test execution, making them perfect for:

• Request correlation and tracing
• Cache busting
• Unique identifiers
• Timestamp-based authentication

Common Patterns

Pattern: SaaS API Monitoring

Content-Type: application/json
Accept: application/json
X-API-Key: [your-api-key]
X-Request-Source: monitoring

Pattern: Internal Microservices

Authorization: Bearer [service-token]
X-Correlation-ID: monitor-{{uuid}}
X-Service-Name: pingward-monitor
X-Tenant-ID: internal

Pattern: GraphQL APIs

Content-Type: application/json
Accept: application/json
X-Apollo-Operation-Name: HealthCheck
X-Request-ID: {{uuid}}

Pattern: REST API with Versioning

Accept: application/json
Accept-Version: v2
X-Request-ID: monitor-{{uuid}}
Cache-Control: no-cache

Headers to Avoid

Some headers are set automatically by Pingward and should not be overridden:

• Host - Automatically set based on the URL (use Host Header field for IP address monitoring instead)
• Content-Length - Automatically calculated from request body
• User-Agent - Set to identify Pingward (can be overridden if needed)
• Connection - Managed by the HTTP client
• Transfer-Encoding - Managed automatically

Overriding these may cause unexpected behavior or request failures.

Security & Best Practices

Credentials Storage

• Headers are encrypted at rest in the database
• Header values are not logged in public-facing test results
• Use Sanitization to redact sensitive values from logs

Header Limits

• Total header size limit: 8KB
• Individual header value limit: 4KB
• Number of headers: No hard limit, but keep it reasonable (<20)

Best Practices

1. Document Your Headers: Use test description to explain why each header is needed
2. Test Without Headers First: Ensure the basic endpoint works before adding complexity
3. Rotate API Keys: Update headers when you rotate credentials
4. Use Tags: Tag tests by API provider to update related tests together
5. Monitor Header Requirements: If the API changes header requirements, tests will alert you

When NOT to Use Headers

• Standard Authentication: Use the Authentication section for Bearer tokens, API keys, Basic auth
• Request Body Data: Put data in the request body, not headers
• Large Values: Headers have size limits; use request body for large payloads
• Sensitive Data in URLs: Use headers instead of query parameters for secrets

Troubleshooting

Test Fails After Adding Headers

• Check header name spelling and format
• Verify header value doesn't contain special characters without proper encoding
• Check API documentation for required header format
• Review test result details to see actual headers sent

Authentication Still Fails

• Confirm API key/token is valid and not expired
• Check if API requires multiple headers (e.g., both API key AND signature)
• Verify header name matches API requirements exactly (case-sensitive)
• Consider using the Authentication section for better credential management

Cached Responses Despite Headers

• Ensure Cache-Control: no-cache and Pragma: no-cache are both set
• Some CDNs require additional cache-busting headers
• Consider adding to URL query parameters as a last resort

See Also

• Authentication - Dedicated auth configuration
• Request Body - Configuring POST/PUT payloads
• Endpoints - URL configuration
• IP Addresses - Using the Host Header field for IP-based monitoring