---
title: DispatchHandler
description: Configure DispatchHandler in PingGateway to evaluate conditions in order and dispatch requests to the first matching handler
component: pinggateway
version: 2025.11
page_id: pinggateway:reference:DispatchHandler
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/DispatchHandler.html
llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
revdate: 2026-06-02T09:37:52Z
superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/DispatchHandler.html
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)