Skip to content

Latest commit

 

History

History
310 lines (238 loc) · 10.6 KB

webhooks.md

File metadata and controls

310 lines (238 loc) · 10.6 KB

Webhooks and commands

Flecto can forward every change to an HTTP endpoint, run a shell command, or both. This page covers the payload shape, delivery guarantees, and the environment passed to commands.


Sending a webhook

flecto watch config/prod.yaml \
  --webhook https://hooks.example.com/notify \
  --webhook-header "Authorization: Bearer TOKEN"

--webhook-header is repeatable.

Flag Default Description
--webhook-timeout <ms> 5000 Request timeout
--webhook-retries <n> 2 Retry attempts per event
--webhook-format <service> flecto Payload shape: flecto, slack, discord, teams, auto — see Sending to chat

Each request carries identifying headers:

Header Description
X-Flecto-Event-Id Unique id for this event
X-Flecto-Batch-Id Groups events emitted from one file change
X-Flecto-Schema Envelope schema version

Envelope shape

schema_version: "2.0":

{
  "schema_version": "2.0",
  "event_id": "a3485f3c-1d27-4cea-a513-56a78ef468d3",
  "batch_id": "3518ac0a-bca6-4920-b034-780ef55596e9",
  "event_type": "changes",
  "source": "ci",
  "emitted_at": "2026-08-06T01:19:20.915Z",
  "file": "/absolute/path/to/config/prod.yaml",
  "changes": [
    { "type": "changed", "path": "database.pool_size", "before": 5, "after": 20 }
  ],
  "policies": [
    {
      "id": "pool-size-jump",
      "severity": "warn",
      "path": "database.pool_size",
      "message": "Pool size increased from 5 to 20 (>=2x).",
      "pack": "default"
    }
  ]
}

changes[].type is one of changed, added, or removed. policies[].severity is info, warn, or error.

Formal schema: schemas/flecto-envelope-2.0.json. The TypeScript type name is FlectoEnvelope.


Delivery modes

Flag Options Behavior
--delivery-mode best-effort (default), at-least-once at-least-once persists failed events to .flecto-queue/ and retries them
--on-alert-failure warn (default), exit, retry What happens when a command or webhook fails
flecto watch config/prod.yaml \
  --webhook https://hooks.example.com/notify \
  --delivery-mode at-least-once \
  --on-alert-failure retry

Pick best-effort for a chat notification you can afford to miss, and at-least-once when the webhook drives real automation.

Note that at-least-once means exactly that — a receiver may see the same event_id twice, so make handlers idempotent.

A queued event is bound to the destination it was addressed to. .flecto-queue/ holds one directory per destination, keyed by a hash of the URL, headers, and format, and a flush only ever reads its own. Change the webhook URL and the old backlog is not redirected to the new endpoint — it stays queued under the old key until that destination is configured again. Before this binding existed, a flush delivered whatever was queued to whichever endpoint the current run named, so an event could arrive at a different team's channel or a different vendor entirely.

The destination includes the headers, so rotating a webhook token also strands the backlog — the queued events were addressed to the old credential, and replaying them under a new one is a decision for you, not for Flecto. This is the likeliest way to meet a stranded queue in practice.

Events queued by Flecto 3.x sit at the top level of .flecto-queue/ with no destination recorded at all. Those are not deliverable either — where they were headed is not knowable.

Neither kind is deleted. Flecto names both once per workspace:

[warn] .flecto-queue/ holds undelivered events this run will not send: 3 event(s)
queued for a destination that is not the one configured now (rotating a webhook
token or editing the URL does this). They are kept, not dropped.

Each queued file is a Flecto envelope, so re-sending one deliberately is a curl with the body of the file once you have looked at where it was going.


Running a command on change

flecto watch .env --command "docker-compose restart app"

The command runs through your shell on every change, with these variables set:

Variable Description
FLECTO_FILE Absolute path of the changed file
FLECTO_EVENT_ID Unique id for this event
FLECTO_BATCH_ID Groups events from one file change
FLECTO_SCHEMA_VERSION Envelope schema version
FLECTO_CHANGES Changes as a JSON array
FLECTO_CHANGES_FILE Path to a temp file with the payload, for large change sets
FLECTO_CHANGES_TRUNCATED 1 when the payload was too large to pass inline

Because a large payload may be moved out of FLECTO_CHANGES and into a file, robust scripts should check FLECTO_CHANGES_FILE first:

#!/usr/bin/env bash
payload="${FLECTO_CHANGES}"
if [ -n "${FLECTO_CHANGES_FILE}" ]; then
  payload="$(cat "${FLECTO_CHANGES_FILE}")"
fi
echo "${payload}" | jq -r '.[] | "\(.type) \(.path)"'

The spill file holds the complete, unmasked change set — including values --mask-secrets hides on screen. It is written 0600 inside a 0700 .flecto-tmp/, and removed as soon as the command exits, so read it from within the command rather than expecting it to be there afterwards. Earlier versions left it behind with whatever the process umask gave it (0644 on a typical runner), where a later build step, artifact upload, or cache action could pick it up.


Command and webhook together

flecto watch .env \
  --command "make reload" \
  --webhook https://hooks.example.com/notify

Declaring these in .flectorc

command, webhook, and webhook-header are refused when declared in .flectorc (or a profile) rather than passed on the command line:

[error] Refusing "command" declared in .flectorc: it spawns a shell command on
every change, and .flectorc is attacker-controlled on an untrusted pull request.

.flectorc is attacker-controlled on an untrusted pull request. command spawns a shell, webhook sends the change payload to a URL, and webhook-header rides along on that request and can override it — including Content-Type — even when webhook itself is the operator's own flag. All three are actions, not settings, so a repository's own config file cannot declare any of them. Naming them on the command line, as in every example on this page, is operator intent and is unaffected. --delivery-mode and --on-alert-failure are unaffected either way — they only tune how an alert you already configured responds to failure, so .flectorc can set those freely (flecto init does). For a repository that genuinely configures command/webhook/webhook-header in .flectorc:

FLECTO_ALLOW_RC_ALERTS=1 flecto watch .env

Sending to chat

--webhook-format posts a payload the chat service renders natively, so no receiver of your own is needed. Everything else — headers, timeout, retries, delivery modes, --on-alert-failure — works exactly as above; only the request body changes.

flecto watch config/prod.yaml \
  --webhook "https://hooks.slack.com/services/T000/B000/XXXX" \
  --webhook-format slack
Value Body posted
flecto (default) The raw envelope, unchanged
slack Block Kit blocks, plus a text fallback for notifications
discord One embeds[] entry, colored by severity
teams A MessageCard for Office 365 connector webhooks
auto Detected from the webhook host (see below)

The default stays flecto: without the flag, the posted bytes are exactly what earlier versions sent, so existing receivers are unaffected.

In .flectorc the key is webhookFormat:

{
  "profiles": {
    "prod": { "webhookFormat": "slack" }
  }
}

The X-Flecto-Event-Id, X-Flecto-Batch-Id, and X-Flecto-Schema headers are still sent with chat payloads — chat services ignore unknown headers, and they make deliveries traceable.

Auto-detection

--webhook-format auto picks a format from the webhook host:

Host Format
hooks.slack.com (any *.slack.com) slack
discord.com / discordapp.com with an /api/webhooks path discord
*.office.com, *.office365.com (e.g. *.webhook.office.com) teams
anything else flecto

Detection is opt-in rather than automatic, so upgrading never changes what an existing webhook receives. An explicit --webhook-format slack always wins over detection. Power Automate endpoints (*.logic.azure.com) are not detected — set --webhook-format teams for those.

Severity and truncation

The highest policy severity in the event drives the color and emoji:

Severity Emoji Color
error 🔴 #D92D20
warn 🟡 #F79009
info 🔵 #2E90FA
none (no findings) 🟢 #12B76A

Large change sets are truncated rather than posted as a wall of text: at most 20 change lines and 20 policy findings per message, individual values cut at 80 characters, with a trailing … +N more changes / … +N more findings. Text is then fitted to each service's documented maximum:

Service Limit coded against
Slack 3000 chars per section text, 150 per header, 50 blocks per message
Discord 4096 chars per embed description, 256 per title
Teams 28 KB per incoming-webhook message

The full change set is always in the envelope — use --webhook-format flecto (or a second webhook) when a downstream system needs every change.

Note that policy finding messages are rendered verbatim, exactly as they appear in the raw envelope. A pack whose messageTemplate interpolates {before} / {after} can therefore surface a value that --mask-secrets-webhooks redacted from changes. Keep secret-bearing paths out of message templates.


Secret masking in payloads

--mask-secrets alone only affects terminal output. To redact secret-like values in the webhook payload too:

flecto watch .env --mask-secrets --mask-secrets-webhooks

Masking happens before the envelope is built, so it applies to every --webhook-format — a Slack, Discord, or Teams message renders the same *** placeholders the raw envelope carries.

See configuration for what counts as secret-like.


Migrating from envelope 1.1

  • schema_version is now "2.0"
  • The type name is FlectoEnvelope
  • Change envelopes carry a new policies array
  • Webhook headers are unchanged (X-Flecto-*)