Skip to main content

HTTP Headers

Custom outgoing headers can be injected into any HTTP request using the [headers] table. This table maps header names (keys) directly to their respective values. Rumour supports robust dynamic values, parent/child environment inheritance, case preservation, and path-based dependency references.

1. Setup Environment​

To set up a test environment from scratch and replicate the workspace example, follow these steps:

A. Initialize the Workspace​

Create a new directory and initialize a clean, zero-clutter Rumour workspace root:

mkdir header_example
cd header_example
rumour init

B. Scaffold Modular Collections​

Scaffold two modular collections inside the workspace (auth and users) using the scaffolding tool:

rumour new auth 
rumour new users

2. Directory Structure & File Contents​

After setting up the workspace, your directory structure will look like this:

header_example/
├── workspace.env.toml
├── header_example.config.toml
├── header_example.suite.toml
├── auth/
│   ├── auth.config.toml
│   ├── auth.env.toml
│   ├── auth.suite.toml
│   └── requests/
│       └── login.toml
└── users/
    ├── users.config.toml
    ├── users.env.toml
    ├── users.suite.toml
    └── requests/
        └── get_users.toml

Here are the complete contents for each file in this setup:

A. Workspace Level Files​

workspace.env.toml​

Defines base variables and global environment definitions.

# workspace.env.toml
[variables]
base_url = "https://httpbin.org"
"env.ENV_STAGE" = "staging"

header_example.config.toml​

Workspace-level request runner configurations.

[config]
# timeout_ms = 5000
# max_retries = 3

header_example.suite.toml​

Global ordered execution suite.

[suite]
name = "Workspace Workflow Suite"
description = "Global ordered execution suite for all workspace request workflows."
ordered = true

requests = [
    # Add paths to your requests or modular collection suites here
]

B. auth Collection Files​

auth/auth.config.toml​

Collection-level configuration for the auth collection.

[config]
# timeout_ms = 5000
# max_retries = 3
# retry_backoff_ms = 500

auth/auth.env.toml​

Collection-level variables for the auth collection.

[variables]
# Collection-level variables for the 'auth' collection.
# These will override workspace-level variables in your workspace.env.toml.

auth/auth.suite.toml​

Modular suite for executing auth requests.

[suite]
name = "Auth Workflow Suite"
description = "Modular ordered execution suite for Auth request workflows."
ordered = true

requests = [
    "requests/login.toml"
]

auth/requests/login.toml​

Performs authentication and extracts the returned token from the JSON body payload.

# auth/requests/login.toml
[request]
method = "POST"
url = "{{base_url}}/post"

[body]
raw = '{"username": "admin", "token": "session_secret_xyz123"}'

[extract]
token = "json.token"

C. users Collection Files​

users/users.config.toml​

Collection-level configurations.

[config]
# timeout_ms = 5000
# max_retries = 3
# retry_backoff_ms = 500

users/users.env.toml​

Collection-level variables.

[variables]
# Collection-level variables for the 'users' collection.
# These will override workspace-level variables in your workspace.env.toml.

users/users.suite.toml​

Modular suite for executing users requests.

[suite]
name = "Users Workflow Suite"
description = "Modular ordered execution suite for Users request workflows."
ordered = true

requests = [
    "requests/get_users.toml"
]

users/requests/get_users.toml​

Consumes the token extracted by login.toml, resolves environment files, local variables, vault secrets, and dynamic placeholders.

# users/requests/get_users.toml
[dependencies]
"../../auth/requests/login.toml" = "token"

[request]
method = "GET"
url = "{{base_url}}/headers"

[headers]
# 1. Access variable extracted from a dependency (relative file path)
Authorization = "Bearer {{../../auth/requests/login.token}}"

# 2. Access local variable defined in the [variables] block below
X-Custom-Client = "{{client_name}}"

# 3. Access environment variable from env files / environment
X-Environment = "{{env.ENV_STAGE}}"

# 4. Access secrets securely from the vault
X-Vault-Token = "{{vault.SECURE_KEY}}"

# 5. Case preservation check
X-Preserve-CASE = "Active"

# 6. Dynamic placeholders
X-Request-Timestamp = "{{timestamp}}"
X-Request-RandomID = "req-{{random}}"

[variables]
client_name = "RumourTestAgent/2.0"

3. Run the Requests & Outputs​

To run the execution of the main request, run the following command. The runner automatically detects the dependency on login.toml, executes it, extracts the token, and passes it to get_users.toml. Since we use vault secrets, pass the vault decryption password as well:

Command​

RUMOUR_VAULT_PASS=mypassword123 rumour run users/requests/get_users.toml -vt

Output​

~/workspace/testing/header_example main* ❯ RUMOUR_VAULT_PASS=mypassword123 rumour run users/requests/get_users.toml -vt

  POST https://httpbin.org/post
  Body (json): {"username": "admin", "token": "session_secret_xyz123"}
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/header_example/auth/requests/login.toml (991ms)
  GET https://httpbin.org/headers
  Header: X-Environment: staging
  Header: X-Vault-Token: super_secure_vault_value_987
  Header: X-Request-Timestamp: 1779258428670
  Header: Authorization: Bearer session_secret_xyz123
  Header: X-Custom-Client: RumourTestAgent/2.0
  Header: X-Preserve-CASE: Active
  Header: X-Request-RandomID: req-82a02c73
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/header_example/users/requests/get_users.toml (240ms)
    ✓ users/requests/get_users.toml → PASS (2 Pass, 0 Fail, 0 Skip)                                                                   
╭──────────────────────────────────────────────────────────────────────────╮
│ RUMOUR EXECUTION REPORT                                                  │
├──────────────────────────────────────────────────────────────────────────┤
│ Total Requests:      2                                                   │
│ Successful:          2                                                   │
│ Failed:              0                                                   │
│ Skipped:             0                                                   │
│ Success Rate:        100.0%                                              │
│ Total Time:          1265ms                                              │
╰──────────────────────────────────────────────────────────────────────────╯

✓ Successful Requests:
  - /home/bugsfounder/workspace/testing/header_example/auth/requests/login.toml  [200] [992ms]
  - /home/bugsfounder/workspace/testing/header_example/users/requests/get_users.toml  [200] [272ms]

Actionable Recommendations:
  → Run with --json to export this report for your CI/CD pipeline.

4. Header Value Resolution Types​

Rumour supports multiple resolution types for dynamic headers:

A. Local Variables​

Define variables in the request TOML under the [variables] section.

  • Syntax: {{variable_name}}
  • Example: X-Custom-Client = "{{client_name}}"

B. Environment Variables​

Source variables from env files (e.g. workspace.env.toml) or system environment.

  • Syntax: {{env.VAR_NAME}}
  • Example: X-Environment = "{{env.ENV_STAGE}}"

C. Secure Vault Secrets​

Reference credentials encrypted in Rumour's credential vault.

  • Syntax: {{vault.SECRET_KEY}}
  • Example: X-Vault-Token = "{{vault.SECURE_KEY}}"

D. Dynamic Generators & Placeholders​

  • {{random}}: Injects a 12-digit random numeric suffix.
  • {{timestamp}} or {{timestamp_ms}}: Current Unix epoch in milliseconds.
  • {{timestamp_sec}}: Current Unix epoch in seconds.

5. Dependency Resolution Options & Recommendations​

When referencing extracted values from dependency requests (like token), you have two distinct syntaxes:

Option 1: Direct Dotted Relative Path (Explicit)​

You can directly reference the path of the dependency file relative to the current request folder, followed by the variable name.

[headers]
Authorization = "Bearer {{../../auth/requests/login.token}}"

Option 2: Simple Local Mapping​

Alternatively, you can reference the token directly using the short-hand local variable name:

[headers]
Authorization = "Bearer {{token}}"
info

While using Authorization = "Bearer {{token}}" works directly, it is not recommended if your workspace has multiple upstream requests extracting same-named variables (e.g., auth.token, product.token, user.token).

Under ambiguous conditions, Rumour might get confused and resolve the wrong token value.

To keep your header values clean, readable, and deterministic, it is highly recommended to declare and map dependencies explicitly at the bottom of your request file:

# Place this at the bottom of users/requests/get_users.toml
[dependencies]
"../../auth/requests/login.toml" = "token"

This maps the value of token extracted from login.toml specifically to a local variable named token within this file's namespace, avoiding resolving collisions.

For more details on execution and graphs, refer to the Dependency Overview and Explicit Dependencies sections.

6. Inspecting Outgoing Request Payloads​

To audit the exact payload and headers transmitted:

  • Verbose CLI Logging (-v / -vt): Details outgoing HTTP headers, query params, and body payloads in real-time.
  • JSON Output (--json): Outputs a request_sent block containing exact transmission parameters.
  • Echo Server Headers: Standard headers received by the server are returned in the response body when hitting echo hosts.
Vault Troubleshooting

If Rumour fails execution with a Variable Resolution Error complaining about a missing vault.SECURE_KEY, ensure you have correctly set the RUMOUR_VAULT_PASS environment variable when launching the run to unlock the vault.