This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Cloud Config 5.0.5!

Push Notifications and Spring Cloud Bus

Many source code repository providers (such as Github, Gitlab, Gitea, Gitee, Gogs, or Bitbucket) notify you of changes in a repository through a webhook. You can configure the webhook through the provider’s user interface as a URL and a set of events in which you are interested. For instance, Github uses a POST to the webhook with a JSON body containing a list of commits and a header (X-Github-Event) set to push. If you add a dependency on the spring-cloud-config-monitor library and activate the Spring Cloud Bus in your Config Server, then a /monitor endpoint is enabled.

When the webhook is activated, the Config Server sends a RefreshRemoteApplicationEvent targeted at the applications it thinks might have changed. The change detection can be strategized. However, by default, it looks for changes in files that match the application name (for example, foo.properties is targeted at the foo application, while application.properties is targeted at all applications). The strategy to use when you want to override the behavior is PropertyPathNotificationExtractor, which accepts the request headers and body as parameters and returns a list of file paths that changed.

The default configuration works out of the box with Github, Gitlab, Gitea, Gitee, Gogs or Bitbucket. In addition to the JSON notifications from Github, Gitlab, Gitee, or Bitbucket, you can trigger a change notification by POSTing to /monitor with form-encoded body parameters in the pattern of path={application}. Doing so broadcasts to applications matching the {application} pattern (which can contain wildcards).

The RefreshRemoteApplicationEvent is transmitted only if the spring-cloud-bus is activated in both the Config Server and in the client application.
The default configuration also detects filesystem changes in local git repositories. In that case, the webhook is not used. However, as soon as you edit a config file, a refresh is broadcast.

HTTP Property Path Notifications

The Config Server can notify applications directly over HTTP instead of using Spring Cloud Bus. When Spring Cloud Bus is not available, the HTTP notifier is used automatically.

When Spring Cloud Bus is available and enabled, the Bus notifier takes precedence.

The HTTP notifier discovers application instances through a DiscoveryClient and sends a POST request to the refresh endpoint of each affected instance. A DiscoveryClient implementation must be available on the classpath for HTTP notifications to be enabled.

By default, the refresh endpoint is:

/actuator/refresh

The refresh endpoint can be customized for individual services with the following property:

spring:
  cloud:
    config:
      server:
        monitor:
          http:
            endpoints:
              orders: /management/refresh
              inventory: /actuator/custom-refresh

You can also provide the refresh endpoint as refresh-endpoint metadata on a ServiceInstance. The service-specific configuration takes precedence over instance metadata.

When neither a configured endpoint nor instance metadata is available, /actuator/refresh is used.

The target applications must expose the configured refresh endpoint for HTTP notifications to succeed.

Webhook Secret Validation

To prevent unauthenticated parties from triggering configuration refreshes, the Config Server can validate incoming webhook requests against a shared secret configured in your repository provider. When a secret is configured for a provider, the /monitor endpoint will reject any request from that provider that does not carry a valid signature or token, returning HTTP 403.

If no secrets are configured at all, the /monitor endpoint will reject all incoming webhook requests. You must configure a webhook secret for each provider whose webhooks you want to accept.

Each provider uses a different mechanism to sign requests. The Config Server supports the following:

Provider Mechanism Property

GitHub

HMAC-SHA256 of the raw request body, sent in the X-Hub-Signature-256 header as sha256=<hex>

spring.cloud.config.server.monitor.github.webhook-secret

GitLab

Plain secret token sent verbatim in the X-Gitlab-Token header

spring.cloud.config.server.monitor.gitlab.webhook-secret

Bitbucket Cloud

HMAC-SHA256 of the raw request body, sent in the X-Hub-Signature header as sha256=<hex>

spring.cloud.config.server.monitor.bitbucket.webhook-secret

Bitbucket Server / Data Center

HMAC-SHA256 of the raw request body, sent in the X-Hub-Signature header as sha256=<hex>

spring.cloud.config.server.monitor.bitbucket.webhook-secret

Gogs

HMAC-SHA256 of the raw request body, sent in the X-Gogs-Signature header (no prefix)

spring.cloud.config.server.monitor.gogs.webhook-secret

Gitea

HMAC-SHA256 of the raw request body, sent in the X-Gitea-Signature header (no prefix)

spring.cloud.config.server.monitor.gitea.webhook-secret

Gitee

See Gitee validation modes below

spring.cloud.config.server.monitor.gitee.webhook-secret

Gitee Validation Modes

Gitee supports two webhook authentication modes, selected by whether the X-Gitee-Timestamp header is present in the request:

  • Signature mode (recommended): When X-Gitee-Timestamp is present, the X-Gitee-Token header contains a Base64-encoded HMAC-SHA256 of <timestamp>\n<secret>, keyed with the secret. The Config Server also rejects requests whose timestamp differs from the server clock by more than one hour.

  • Password mode: When X-Gitee-Timestamp is absent, the X-Gitee-Token header is compared directly against the configured secret.

Configure the mode on the Gitee webhook settings page. Signature mode is recommended because it prevents replay attacks.

Disabling Webhook Validation

The validation filter is enabled by default. To disable it entirely, set:

spring:
  cloud:
    config:
      server:
        monitor:
          validation-filter-enabled: false

You can also disable validation for a specific provider while keeping its webhook events processed, by setting its validation-enabled property to false:

spring:
  cloud:
    config:
      server:
        monitor:
          github:
            validation-enabled: false

To disable a provider’s /monitor integration altogether (both validation and event processing), set its enabled property to false:

spring:
  cloud:
    config:
      server:
        monitor:
          github:
            enabled: false