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.
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 |
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.
| 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 retryPick 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.
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.
flecto watch .env \
--command "make reload" \
--webhook https://hooks.example.com/notifycommand, 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--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.
--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.
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.
--mask-secrets alone only affects terminal output. To redact secret-like values
in the webhook payload too:
flecto watch .env --mask-secrets --mask-secrets-webhooksMasking 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.
schema_versionis now"2.0"- The type name is
FlectoEnvelope - Change envelopes carry a new
policiesarray - Webhook headers are unchanged (
X-Flecto-*)