Request Callout

The Request Callout plugin allows you to insert arbitrary API calls before proxying a request to the upstream service.

This plugin is composed of callout objects, where each object specifies the API callout declaratively, with custom query parameters, headers, and request body.

API callout responses are stored in the Kong Gateway shared context under a kong.ctx.shared.callouts.CALLOUT_NAME. Responses can be cached with a TTL.

Content modifications in both callout and upstream bodies assume a JSON content type.

When tls_certificate_verify is enabled in Kong Gateway, certificate verification for this plugin is enforced at runtime, not at configuration time. Since the url field can be set dynamically v3.13+, the plugin cannot validate whether ssl_verify=false is appropriate until the request is processed. If the URL resolves to an HTTPS endpoint with ssl_verify=false, the request will be blocked. Conversely, if the URL resolves to an HTTP endpoint, the configuration is valid and the request proceeds.

Callout request and response context is stored in kong.ctx.shared.callouts.CALLOUT_NAME.

The request context includes:

• .CALLOUT_NAME.request.params: Full callout request config, including url, method, query, headers (case-sensitive), body, decode, ssl_verify, proxy, timeouts, and other HTTP options.
• .CALLOUT_NAME.request.retries: Retry attempts if error = retry, with:
  • reason: error (TCP error) or code (HTTP status code).
  • err: Specific error.
  • http_code: Triggering status code.
• .CALLOUT_NAME.request.n_retries: Total retry count.
• .CALLOUT_NAME.caching: Cache config per plugin schema. If cache_key is set, it overrides the key for the current callout.

The response context contains:

• status
• headers
• body

Header and body storage can be disabled via the config.callouts.response.headers.store and config.callouts.response.body.store parameters.

All custom fields support Lua expressions in the value portion, and any PDK method or Lua function available within the Kong Gateway sandbox can be used. The syntax is the same as the Request Transformer Advanced plugin uses for Lua expressions. In custom values, callouts can be referenced via the shorthand callouts.CALLOUT_NAME instead of the full kong.ngx.shared.callouts.CALLOUT_NAME. Lua expressions don’t carry side effects. If the custom value is a raw string, make sure the string doesn’t start with # or $, as the backend interpreter will read anything following these characters as a Lua expression. If you need to include a # or $ character, change the value to $("$|#RAW STRING"). For example, #1234! is not a valid custom value. To make it valid, pass the value as $("#1234!").

by_lua fields work in a similar way, but they don’t support shortcuts. Shortcuts can produce unintended side effects and modify callout and upstream requests.

Both request and response callout objects may contain a by_lua field:

• request.by_lua runs before the callout request is performed or the cache is queried and is useful to further customize aspects of the request.
• response.by_lua runs after a response is obtained from the service and before it is stored in the cache and is useful to customize aspects of the response.

The upstream object may also contain a by_lua field for Lua code that runs before the upstream request runs. This is useful to further customize the upstream request, or even to bypass it completely, short-circuiting the request and response from Kong Gateway.

Lua code may contain references and modify values in the callout context.

Schema validation will detect syntax issues. Other errors, such as nil references, happen at runtime and will lead to an Internal Server Error. Lua code must be thoroughly tested to ensure that it’s correct and meets performance requirements.

Callout request and upstream request configuration blocks contain a forward flag that controls whether specific request components are used to build the callout or upstream request.

If config.upstream.headers.forward is set to false, this effectively clears all incoming request headers, including essential headers such as Content-Type and Host.

If you need to forward only a subset of headers, you can reinsert a custom list of headers using the config.upstream.headers.custom configuration parameter.

The Request Callout plugin supports caching of callout requests. Globally, the behavior is configured via the config.cache setting.

Cache key

The callout cache key is the SHA-256 of the following proxy request and callout request components:

• Proxy request:
  • Route ID
  • Plugin ID
  • Consumer ID (if a Consumer is set)
  • Consumer Groups (if at least one Consumer Group exists)
• Callout request:
  • Callout name
  • HTTP method
  • Callout URL
  • Callout query params (sorted by key name)
  • Callout headers (sorted by header name)
  • Callout request body (sorted by key name, if a key-value format like JSON is used)

By default, only callout request query and headers are part of the cache key, and incoming proxy request headers and query params are not. If callout headers and query params have a forward flag set, then incoming request headers and query params are forwarded in the callout requests, causing them to be part of the cache key.

Starting in Kong Gateway 3.13, you can authenticate with a cloud Redis provider for your Redis strategy. This allows you to seamlessly rotate credentials without relying on static passwords.

The following providers are supported:

• AWS ElastiCache
• Azure Managed Redis
• Google Cloud Memorystore (with or without Valkey)

Each provider also supports an instance and cluster configuration.

Important: Kong Gateway open source plugins do not support any Redis cloud provider cluster configurations.

To configure cloud authentication with Redis, add the following parameters to your plugin configuration:

config:
  storage: redis
  storage_config:
    redis:
      host: $INSTANCE_ADDRESS
      username: $INSTANCE_USERNAME
      port: 6379
      cloud_authentication:
        auth_provider: aws
        aws_cache_name: $AWS_CACHE_NAME
        aws_is_serverless: false
        aws_region: $AWS_REGION
        aws_access_key_id: $AWS_ACCESS_KEY_ID
        aws_secret_access_key: $AWS_ACCESS_SECRET_KEY

config:
  storage: redis
  storage_config:
    redis:
      cluster_nodes:
      - ip: $CLUSTER_ADDRESS
        port: 6379
      username: $CLUSTER_USERNAME
      port: 6379
      cloud_authentication:
        auth_provider: aws
        aws_cache_name: $AWS_CACHE_NAME
        aws_is_serverless: false
        aws_region: $AWS_REGION 
        aws_access_key_id: $AWS_ACCESS_KEY_ID
        aws_secret_access_key: $AWS_ACCESS_SECRET_KEY 

config:
  storage: redis
  storage_config:
    redis:
      host: $INSTANCE_ADDRESS
      username: $INSTANCE_USERNAME
      port: 6379
      cloud_authentication:
        auth_provider: azure
        azure_client_id: $AZURE_CLIENT_ID
        azure_client_secret: $AZURE_CLIENT_SECRET
        azure_tenant_id: $AZURE_TENANT_ID

config:
  storage: redis
  storage_config:
    redis:
      cluster_nodes:
      - ip: $CLUSTER_ADDRESS
        port: 6379
      username: $CLUSTER_USERNAME
      port: 6379
      cloud_authentication:
        auth_provider: azure
        azure_client_id: $AZURE_CLIENT_ID
        azure_client_secret: $AZURE_CLIENT_SECRET
        azure_tenant_id: $AZURE_TENANT_ID

config:
  storage: redis
  storage_config:
    redis:
      host: $INSTANCE_ADDRESS
      port: 6379
      cloud_authentication:
        auth_provider: gcp
        gcp_service_account_json: $GCP_SERVICE_ACCOUNT

config:
  storage: redis
  storage_config:
    redis:
      cluster_nodes:
      - ip: $CLUSTER_ADDRESS
        port: 6379 
      port: 6379
      cloud_authentication:
        auth_provider: gcp
        gcp_service_account_json: $GCP_SERVICE_ACCOUNT