Sourcing (Valuable)

Introduction

Webhooked's Valuable system provides flexible value sourcing, allowing configuration values to come from multiple sources including environment variables, files, and static references. This enables secure secret management and environment-specific configurations.

Overview

The Valuable pattern allows any configuration value to be sourced from:

# Direct value
secret: "direct-value"

# Listing value
secret:
  values: ["array", "value"]

# Environment variable
secret:
  valueFrom:
    envRef: ENV_VAR_NAME

# File reference
secret:
  valueFrom:
    fileRef: /path/to/file

# Static reference
secret:
  valueFrom:
    staticRef: "static,comma,separated"

Value Sources

Direct value

The simplest form - values directly in configuration

storage:
  - type: redis
    specs:
      host: localhost     # Direct value
      port: 6379          # Direct value
      database: 0         # Direct value

Environment Variables

Source values from environment variables:

security:
  type: github
  specs:
    secret: # Environment Sourced
      valueFrom:
        envRef: GITHUB_WEBHOOK_SECRET

storage:
  - type: redis
    specs:
      host: # Environment Sourced
        valueFrom:
          envRef: REDIS_HOST
      password: # Environment Sourced
        valueFrom:
          envRef: REDIS_PASSWORD

File References

Read values from files (useful for secrets):

security:
  type: custom
  specs:
    apiKey: # File Sourced
      valueFrom:
        fileRef: /run/secrets/api-key

storage:
  - type: postgres
    specs:
      databaseUrl: # File Sourced
        valueFrom:
          fileRef: /run/secrets/db-url

Value Sources Ordering

When you provide multiples references, a priority will be applied as following:

1. Values List

2. Direct Value

3. StaticRef

4. EnvRef

5. FileRef

Security Best Practices

✅ GOOD: Use external source for secrets

secret:
  valueFrom:
    envRef: WEBHOOK_SECRET

❌ BAD: Hardcoded secret

secret: "my-secret-key"  # Don't do this!

Use cases

Secret Rotation

Sometimes, you must handle a rotation in your webhook secrets, you can provide both as a comma separated values in multiples ways:

security:
  type: github
  specs:
    secret:
      valueFrom:
        fileRef: /run/secrets/api-key
        # -- OR --
        envRef: WEBHOOK_SECRET
        # -- OR --
        staticRef: "old_secret,new_secret"  # Don't do this, this is an example

The content of /run/secrets/api-key or WEBHOOK_SECRET can be old_secret,new_secret, when the configuration are reloaded, both secrets are accepted as valide out of the box.

With HashiCorp Vault

# Mount Vault secrets as files
storage:
  specs:
    password:
      valueFrom:
        fileRef: /vault/secrets/database-password

With Azure Key Vault

# Using CSI driver to mount secrets
storage:
  specs:
    apiKey:
      valueFrom:
        fileRef: /mnt/secrets-store/api-key

More will coming... If you found a mising case, don't hesitate to open an issue !