---
title: HeaderFilter
description: Removes, adds, or replaces headers in request or response messages.
component: pinggateway
version: 2026
page_id: pinggateway:reference:HeaderFilter
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/HeaderFilter.html
revdate: 2025-02-13T12:29:30Z
section_ids:
  HeaderFilter-usage: Usage
  HeaderFilter-properties: Properties
  HeaderFilter-example: Examples
  HeaderFilter-example-replacing: Replace host header on an incoming request
  HeaderFilter-example-cookie: Add a header to a response
  HeaderFilter-example-adding: Add headers to a request
  HeaderFilter-example-token: Add a token value to a response
  HeaderFilter-example-logging: Add headers and logging results
---

# HeaderFilter

Removes, adds, or replaces headers in request or response messages.

## Usage

```json
{
  "name": string,
  "type": "HeaderFilter",
  "config": {
    "messageType": configuration expression<enumeration>,
    "remove": [ configuration expression<string>, ... ],
    "add": {
      string: [ runtime expression<string>, ... ], ...
    }
    "replace": {
      string: [ runtime expression<string>, ... ], ...
    }
  }
}
```

## Properties

* \`"messageType": *configuration expression<[enumeration](preface.html#definition-enumeration)>, required*

  The type of message for which to filter headers. Must be either `"REQUEST"` or `"RESPONSE"`.

* `"remove"`: *array of configuration expression<[strings](preface.html#definition-string)>, optional*

  The names of header fields to remove.

* `"add"`: *[object](preface.html#definition-object), optional*

  One or more headers to add with the format `name: [ value, …​ ]`:

  * *name* is a string for a header name.

  * *value* is a runtime expression that resolves to one or more header values.

* `"replace"`: *[object](preface.html#definition-object), optional*

  One or more headers to replace with the format `name: [ value, …​ ]`

  * *name* is a string for a header name.

  * *value* is a runtime expression that resolves to one or more header values.

  PingGateway removes current values for the *name* headers and adds the specified values.

## Examples

### Replace host header on an incoming request

The following example replaces the host header on the incoming request with the value `myhost.com`:

```json
{
  "name": "ReplaceHostFilter",
  "type": "HeaderFilter",
  "config": {
    "messageType": "REQUEST",
    "replace": {
      "host": [ "myhost.com" ]
    }
  }
}
```

### Add a header to a response

The following example adds a `Set-Cookie` header to the response:

```json
{
  "name": "SetCookieFilter",
  "type": "HeaderFilter",
  "config": {
    "messageType": "RESPONSE",
    "add": {
      "Set-Cookie": [ "mysession=12345" ]
    }
  }
}
```

### Add headers to a request

The following example adds the headers `custom1` and `custom2` to the request:

```json
{
  "name": "SetCustomHeaders",
  "type": "HeaderFilter",
  "config": {
    "messageType": "REQUEST",
    "add": {
      "custom1": [ "12345", "6789" ],
      "custom2": [ "abcd" ]
    }
  }
}
```

### Add a token value to a response

The following example adds the value of session's policy enforcement token to the `pef_sso_token` header in the response:

```json
{
  "type": "HeaderFilter",
  "config": {
    "messageType": "RESPONSE",
    "add": {
      "pef_sso_token": ["${session.pef_token}"]
    }
  }
}
```

### Add headers and logging results

The following example adds a message to the request and response as it passes through the Chain and the `capture` on the ReverseProxyHandler logs the result.

```json
{
  "condition": "${find(request.uri.path, '^/home/chain')}",
  "handler": {
    "type": "Chain",
    "comment": "Base configuration defines the capture decorator",
    "config": {
      "filters": [
        {
          "type": "HeaderFilter",
          "comment": "Add a header to all requests",
          "config": {
            "messageType": "REQUEST",
            "add": {
              "MyHeaderFilter_request": [
                "Added by HeaderFilter to request"
              ]
            }
          }
        },
        {
          "type": "HeaderFilter",
          "comment": "Add a header to all responses",
          "config": {
            "messageType": "RESPONSE",
            "add": {
              "MyHeaderFilter_response": [
                "Added by HeaderFilter to response"
              ]
            }
          }
        }
      ],
      "handler": {
        "type": "ReverseProxyHandler",
        "config": {
          "tls": "ClientTlsOptions"
        },
        "comment": "Log request, pass it to the sample app, log response",
        "capture": "all",
        "baseURI": "https://app.example.com:8444"
      }
    }
  }
}
```

Source: [chain.json](../_attachments/config/routes/chain.json)

The chain receives the request and context and processes it as follows:

* The first `HeaderFilter` adds a header to the incoming request.

* The second `HeaderFilter` manages responses not requests, so it simply passes the request and context to the handler.

* The `ReverseProxyHandler` captures (logs) the request.

* The `ReverseProxyHandler` forwards the transformed request to the protected application.

* The protected application passes a response to the `ReverseProxyHandler`.

* The `ReverseProxyHandler` captures (logs) the response.

* The second `HeaderFilter` adds a header added to the response.

* The first `HeaderFilter` is configured to manage requests, not responses, so it simply passes the response back to PingGateway.

The following example lists some of the HTTP requests and responses captured as they flow through the chain. You can search the log files for `MyHeaderFilter_request` and `MyHeaderFilter_response`.

```http
# Original request from user-agent
GET https://ig.example.com:8443/home/chain HTTP/1.1
Accept: /
Host: ig.example.com:8443

# Add a header to the request (inside PingGateway) and direct it to the protected application
GET https://app.example.com:8444/home/chain HTTP/1.1
Accept: /
Host: ig.example.com:8443
MyHeaderFilter_request: Added by HeaderFilter to request

# Return the response to the user-agent
HTTP/1.1 200 OK
Content-Length: 1809
Content-Type: text/html; charset=UTF-8

# Add a header to the response (inside PingGateway)
HTTP/1.1 200 OK
Content-Length: 1809
MyHeaderFilter_response: Added by HeaderFilter to response
```