Webhook Source

This guide explains how to set up the Webhook notification source for the Reloader component in your environment. Using webhooks as a notification source lets you trigger secret rotation events by sending HTTP POST requests to the Reloader process.

How it works

The controller runs a single shared HTTP server for all Config resources. The listen address is set with the controller flag --webhook-bind-address (default :8090). Each cluster-scoped Config is exposed at:

POST /webhook/<Config.metadata.name>

When a webhook source sets pathSuffix, the route becomes:

POST /webhook/<Config.metadata.name>/<pathSuffix>

There is no per-CR bind address; callers use the Config name and optional suffix in the path.

Breaking changes (v2.0.0)

Per-CR path and address fields were removed from WebhookConfig. Webhooks now use the shared listener configured via --webhook-bind-address and the fixed route pattern above. Upgrade callers to POST to /webhook/<Config.metadata.name> on the shared bind address instead of per-Config URLs.

Configuration

Configure a NotificationSource with type: Webhook and a webhook block. The main field is identifierPathOnPayload (JSON path in the body where the secret name appears).

Key fields

• identifierPathOnPayload: JSON path in the POST body for the secret identifier. It must match the name of the secret being rotated. If omitted, the default path is 0.data.ObjectName.
• pathSuffix (optional): URL path segment for this webhook source. When set, callers POST to /webhook/<Config.metadata.name>/<pathSuffix>. Use distinct suffixes when a Config defines multiple webhook notification sources. At most one webhook source may omit pathSuffix.
• webhookAuth (optional): Basic or bearer authentication for incoming requests.
• retryPolicy (optional): Retry failed publishes to the internal event channel.

Multiple webhook sources on one Config

A Config can define more than one type: Webhook entry. Give each source a unique pathSuffix so callers know which endpoint to use:

notificationSources:
  - type: Webhook
    webhook:
      pathSuffix: keeper-security
      identifierPathOnPayload: "0.data.ObjectName"
  - type: Webhook
    webhook:
      pathSuffix: vault-events
      identifierPathOnPayload: "secret.name"

For a Config named keeper, callers POST to /webhook/keeper/keeper-security or /webhook/keeper/vault-events. Each pathSuffix must be unique within the Config, and at most one webhook source may omit it; duplicates (including multiple empty values) are rejected when listeners are managed.

Payload structure

The POST body must be JSON containing the secret identifier at the configured path.

Example payload

{
  "0": {
    "data": {
      "ObjectName": "my-secret"
    }
  }
}

Here the identifier is at 0.data.ObjectName, matching the secret name my-secret.

Triggering a webhook notification

Send an HTTP POST to the Reloader webhook base URL with path /webhook/<your-config-name> or /webhook/<your-config-name>/<pathSuffix> when pathSuffix is set.

curl -X POST "http://<reloader-host>:<webhook-port>/webhook/my-reloader-config" \
  -H "Content-Type: application/json" \
  -d '{
    "0": {
      "data": {
        "ObjectName": "my-secret"
      }
    }
  }'

Replace my-reloader-config with the metadata.name of your Config CR.

Helm

If you use the chart under deploy/charts/reloader, set service.webhook.enabled: true. The chart then adds --webhook-bind-address and a webhook container port using service.webhook.listenPort (default 8090, matching the controller default and the optional *-webhook Service). You can still override the flag with extraArgs if needed.

There is no default “main” HTTP Service on port 8080. ingress.enabled requires service.webhook.enabled: the Ingress targets the {{ release }}-webhook Service on service.webhook.port (paths such as /webhook/...).

Any client that can reach the Service or host on that port can trigger rotation as long as the JSON path and optional auth match your Config.