Change-event sources

Embed
Preview of the card
<a href="https://forumulate.com/p/watchtower/docs/change-events"><img src="https://forumulate.com/api/public/orgs/watchtower/spaces/docs/pages/163f4c4e-4feb-426d-a4b6-8baf2504a6a0/social-card.svg?v=3e7ae33eec8b" alt="Change-event sources" width="600" height="315"></a>

Flag services and CI tools post changes to Watchtower; they appear as chart annotations and as candidates in change analysis (/analysis/changes).

Set up

  1. Settings, Change sources, pick the provider, Create (needs manage_connectors), or POST /v1/projects/{p}/change-sources {"kind": "...", "mapping": {"service": "api", "env": "production"}}.

  2. The response holds the URL /v1/changes/{source_id} and a secret, shown once. Only its SHA-256 is stored. mapping.service / mapping.env are defaults for events that carry neither.

  3. Configure the provider to POST to that URL.

Verification per provider

Provider

How the request is checked

LaunchDarkly

X-LD-Signature: HMAC-SHA256 of the body, key = signing_key

Statsig

X-Statsig-Signature: v0=<hmac> over v0:<X-Statsig-Request-Timestamp>:<body>, key = signing_key

CircleCI

circleci-signature: v1=<hmac> of the body, key = signing_key

Unleash

the secret as Authorization (Bearer optional)

Flagsmith

the secret in X-Flagsmith-Token or Authorization

EventBridge

the secret as the API-destination key (X-Api-Key)

Buildkite

the secret as X-Buildkite-Token

Harness

the secret in X-Harness-Token or Authorization

signing_key is returned at create for the HMAC providers: the hex of the SHA-256 of the secret, the same value the server keeps. Treat it as a secret too. A failed check is 401 and stores nothing.

Events

Each payload becomes change_events rows (kind flag, deploy or pipeline) with service, env, actor, summary, url and at in the event; fields that are not mapped stay in details. Redelivery of the same provider event id is ignored (the response says how many were stored). Limits: 600 requests per minute per source (429 with Retry-After), body up to 256 KiB (413). Delivery is at-least-once; a provider that retries is safe.

Updated