add-header

The internal:add-header interceptor adds headers to the upstream request before it reaches the backend.

Registration

actions:
  - target: "$.paths['/api'].get"
    update:
      x-plenum-interceptor:
        - module: "internal:add-header"
          hook: on_request
          function: onRequest
          options:
            headers:
              x-custom: "my-value"
              x-request-id: "${{header.x-request-id}}"

Hook

Hook	Function	Can short-circuit
on_request	onRequest	No (always continue)

Options

Field	Type	Default	Description
headers	Record<string, string | null>	{}	Headers to add to the upstream request

Headers in options.headers are merged into the upstream request headers. A value of null deletes an existing header. Use ${{...}} interpolation tokens in header values to inject request-derived data.

Behaviour

• Missing or empty options.headers is a no-op — the interceptor passes through.
• Does not short-circuit. Returns { action: "continue" } unconditionally.
• Headers that match existing upstream headers will overwrite them.

Example

Add a request ID and a tracing header to every request:

actions:
  - target: "$.paths[*]"
    update:
      x-plenum-interceptor:
        - module: "internal:add-header"
          hook: on_request
          function: onRequest
          options:
            headers:
              x-request-id: "${{header.x-request-id}}"
              x-forwarded-for: "${{header.x-forwarded-for}}"

See also

• Interceptors overview — writing and registering interceptors
• Interpolation — ${{...}} token syntax in headers