---
title: DispatchHandler
description: When a request is handled, the first condition in the list of conditions is evaluated. If the condition expression yields true, the request is dispatched to the associated handler with no further processing. Otherwise, the next condition in the list is evaluated.
component: pinggateway
version: 2026
page_id: pinggateway:reference:DispatchHandler
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/DispatchHandler.html
revdate: 2025-10-15T18:45:22Z
section_ids:
  DispatchHandler-usage: Usage
  DispatchHandler-properties: Properties
  DispatchHandler-example: Example
  DispatchHandler-moreinfo: More information
---

# DispatchHandler

When a request is handled, the first condition in the list of conditions is evaluated. If the condition expression yields `true`, the request is dispatched to the associated handler with no further processing. Otherwise, the next condition in the list is evaluated.

## Usage

```none
{
  "name": string,
  "type": "DispatchHandler",
  "config": {
    "bindings": [
      {
        "condition": runtime condition<boolean>,
        "handler": Handler reference,
        "baseURI": runtime expression<url>,
      }, ...
    ]
  }
}
```

## Properties

* `"bindings"`: *array of [objects](preface.html#definition-object), required*

  One or more condition and handler bindings.

  * `"condition"`: *runtime condition<[boolean](preface.html#definition-boolean)>, optional*

    A flag to indicate that a condition is met. The condition can be based on the request, context, or PingGateway runtime environment, such as system properties or environment variables.

    Use a [condition](Conditions.html) as the value. PingGateway evaluates the condition's expression, taking the following action depending on the result:

    * `true`: The request is dispatched to the associated handler.

    * `false`: The next condition in the list is evaluated.

    You can find examples in [Example conditions and requests](Route.html#route-conditions).

    Default: `true`

  * `"handler"`: *Handler [reference](preface.html#definition-reference), required*

    The [Handler](Handlers.html) to which PingGateway dispaches the request if the associated condition yields `true`.

    Provide the name of a Handler object defined in the heap or an inline Handler configuration object.

  * `"baseURI"`: *runtime expression<[url](preface.html#definition-url)>,optional*

    A base URI that overrides the existing request URI. Only scheme, host, and port are used in the supplied URI.

    The result of the expression must be a string that represents a valid URI, but isn't a real `java.net.URI` object. For example, it would be incorrect to use `${request.uri}`, which isn't a String but a MutableUri.

    In the following example, the binding condition looks up the hostname of the request. If it finds a match, the value is used for the `baseURI`. Otherwise, the default value is used:

    ```json
    {
      "properties": {
        "uris": {
          "app1.example.com": {
            "baseURI": "https://backend1:8443/"
          },
          "app2.example.com": {
            "baseURI": "https://backend2:8443/"
          },
          "default": {
            "baseURI": "https://backend3:8443/"
          }
        }
      },
      "handler": {
        "type": "DispatchHandler",
        "config": {
          "bindings": [
            {
              "condition": "${not empty uris[contexts.router.originalUri.host]}",
              "baseURI": "${uris[contexts.router.originalUri.host].baseURI}",
              "handler": "ReverseProxyHandler"
            },
            {
              "baseURI": "${uris['default'].baseURI}",
              "handler": "ReverseProxyHandler"
            }
          ]
        }
      }
    }
    ```

    Default: No change to the base URI

## Example

You can find an example that uses a DispatchHandler in [With a DispatchHandler](../gateway-guide/not-enforced-uri.html#not-enforced-uri-dispatch).

## More information

[Expressions](Expressions.html#Expressions)