HTTP Header Case Sensitivity in API Integrations

When building integrations between services, especially those involving secret headers for authentication or configuration, you might encounter a subtle but critical issue that can break your integration in production: HTTP header case sensitivity.

The Problem

HTTP headers are case-insensitive according to the HTTP specification (RFC 7230), but different tools and clients handle header casing differently. This means the same header can appear as:

• Authorization
• authorization
• AUTHORIZATION
• AuthorizAtion

This inconsistency becomes a major problem when your code expects headers in a specific case format.

Real-World Scenario

Imagine you're building an integration between two services where a secret API key is passed via a custom header:

// Your handler expecting 'x-api-secret'
const apiSecret = event.headers['x-api-secret'];
if (!apiSecret) {
    return { statusCode: 401, body: 'Unauthorized' };
}        

This works perfectly during development when testing with curl:

curl -H "x-api-secret: mysecret123" https://yourapi.com/webhook        

But fails in production when the calling service sends:

X-API-SECRET: mysecret123        

Your integration breaks because event.headers['x-api-secret'] returns undefined, while the actual header is stored as event.headers['X-API-SECRET'].

Why This Happens

Different HTTP clients handle header casing differently:

• curl: Preserves the exact case you specify
• Postman: May normalize to Title-Case
• Browser fetch(): Typically converts to lowercase
• Various SDKs: Each has its own behavior
• Proxy servers: May modify header casing
• Load balancers: Can change casing during forwarding

The Solution: Header Normalization

The most robust approach is to normalize all header keys to a consistent case (usually lowercase) immediately when processing the request:

// Example using ScriptRunner Connect
export default async function (event: HttpEventRequest, context: Context<EV>) {
    const headers = event.headers;

    // Normalize all header keys to lowercase
    const normalizedHeaders = Object.fromEntries(
        Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value])
    );

    // Now safely reference headers in lowercase
    const apiSecret = normalizedHeaders['x-api-secret'];
    const contentType = normalizedHeaders['content-type'];
    const authorization = normalizedHeaders['authorization'];

    if (!apiSecret) {
        return { statusCode: 401, body: 'Unauthorized' };
    }

    // Your integration logic here...
}        

Alternative Approaches

1. Case-Insensitive Header Lookup Function

Create a helper function for header lookups:

function getHeader(headers, name) {
    const lowerName = name.toLowerCase();
    const key = Object.keys(headers).find(k => k.toLowerCase() === lowerName);
    return key ? headers[key] : undefined;
}

// Usage
const apiSecret = getHeader(event.headers, 'x-api-secret');        

2. Using a Map with Case-Insensitive Keys

const headerMap = new Map(
    Object.entries(event.headers).map(([key, value]) => [key.toLowerCase(), value])
);

const apiSecret = headerMap.get('x-api-secret');        

Best Practices

1. Always normalize headers early in your request processing pipeline
2. Document the expected header names in your API documentation using lowercase
3. Test with different tools during development (curl, Postman, actual client SDKs)
4. Use integration tests that simulate real-world header casing scenarios
5. Log header keys during debugging to see what casing is actually being received

Testing Your Integration

Create test cases that verify your header handling works with different cases:

const testCases = [
    { 'x-api-secret': 'test123' },
    { 'X-API-SECRET': 'test123' },
    { 'X-Api-Secret': 'test123' },
    { 'x-API-secret': 'test123' }
];

testCases.forEach(headers => {
    // Your handler should work with all of these
    const result = yourHandler({ headers });
    console.assert(result.statusCode === 200);
});
        

Conclusion

Header case sensitivity is a common source of integration failures that often only surface in production. By normalizing header keys early in your request processing, you can avoid these issues entirely and build more robust integrations.

Remember: HTTP headers are case-insensitive by specification, so your code should treat them as such too.

Have you encountered header case sensitivity issues in your integrations? Share your experiences and solutions in the comments below.