Slack Alerts
Set BARCA_SLACK_WEBHOOK_URL to a Slack incoming webhook
and barca posts to its channel when a job starts failing, when it recovers, and once a
day while it keeps failing. It never posts for an ordinary success, a fully cached run, a
skipped barca serve tick, a cancelled run or a run that was killed. Like Datadog it covers
barca get, barca run and every run barca serve starts.
Slack is the only built-in alert. For email, PagerDuty or anything else, have your own monitor
read run outcomes from barca history --json, or from the server’s GET /runs.
Turning it on
Section titled “Turning it on”export BARCA_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T000/B000/XXXXbarca serve --timezone utcThe variable is the whole switch: Slack is not named in BARCA_TELEMETRY (naming it there is
an unknown-integration warning that names this variable). Unset or empty, Slack is off and silent. A
generic SLACK_WEBHOOK_URL, which CI systems and other tools set, is ignored. Set the variable
on the deployment only: a laptop with it exported posts its own failures too.
| Variable | Meaning | Default |
|---|---|---|
BARCA_SLACK_WEBHOOK_URL |
the incoming webhook URL; it must be https://. Any other value is a warning and nothing is sent |
unset (off) |
BARCA_SLACK_NOTIFY |
changes: starts failing, recovered, and the daily reminder. failures: every failed run, plus recovered. all: every finished run that executed at least one step |
changes |
BARCA_UI_URL |
base URL of the web UI (as reached through its proxy, e.g. https://barca.example.com/ui/); the run id in a post links to that run |
unset, no link |
When it posts
Section titled “When it posts”A job is the canonical resolved target, the same as barca.job on a Datadog span:
nightly and pipeline.py:nightly are one job. After each finished run barca compares its
outcome with the job’s previous finished run in the metadata database and with the last post
it made for the job, so it works the same across separate CLI processes and across a server
restart:
| Previous run | This run | changes posts |
|---|---|---|
| success, or none | failed | is failing |
| failed | failed | is still failing, if the last post for the job was 24 hours ago or more |
| failed | success | recovered |
| success | success | nothing |
A run where every step was cached counts as a success. A cancelled run, a skipped tick and a
run recorded as interrupted do not change the job’s state.
What a post looks like
Section titled “What a post looks like”What a post looks like (the run id links to the web UI when BARCA_UI_URL is set):
🔴 pipeline.py:daily_revenue is failingStep pipeline.py:orders failed after 3 attempts in 4m 12sKeyError: 'region'env prod · host barca-prod-1 · run 0179afe0cb58barca history 0179afe0cb58✅ pipeline.py:daily_revenue recoveredFailing since 2026-10-19 06:00 UTC (4 runs)env prod · host barca-prod-1 · run 0179b2a1c4d0A post is one Block Kit message with a plain text fallback. It carries the job, the first
failed step (and how many failed), the exception type and the first line of its message (at
most 300 characters), attempts, duration, env, host and run id. Tracebacks are not sent. The
wording is not a contract and may change in any release.
Delivery
Section titled “Delivery”The post goes out after the run’s results are recorded, within the same 3-second limit as every telemetry integration, and never changes the run’s outcome or exit code. When the webhook cannot be reached or refuses the post, stderr gets the usual telemetry warning, naming the failure category and never the webhook URL:
[barca] warning: telemetry 'slack' did not receive run 0179afe0cb58: HTTP 404Categories are connection failed, HTTP <code> (HTTP 429 (rate limited) when Slack
rate-limits), no reply within 3s and request failed. barca does not wait out a 429. A post
that was not delivered is not recorded, so the next run of the job posts the transition again.
Creating the webhook
Section titled “Creating the webhook”At api.slack.com/apps choose Create New App, then From a manifest, pick the workspace and paste:
display_information: name: barca description: Job failures and recoveries from barcaoauth_config: scopes: bot: - incoming-webhooksettings: org_deploy_enabled: false socket_mode_enabled: false token_rotation_enabled: falseThen Install to Workspace, choose the channel, and copy the webhook URL from Incoming
Webhooks. The URL is a secret: anyone holding it can post to that channel, so keep it out of
barca.toml and the repository. A webhook posts to one channel; to route projects to different
channels, give each deployment its own webhook.
Limits
Section titled “Limits”- A run that fails before it starts (a syntax error, an unknown target, a shared-state pull that fails) is not a finished run and posts nothing, as with Datadog.
- With shared remote state, the record of the last post travels with the metadata database when the run pushes it. A run whose push conflicts and is replayed can lose that record, and the next run may then post the same transition again. Two runs of one job finishing at the same moment can both post.
- A run without targets is the job
all, whatever files it reads. - The reminder interval is fixed at 24 hours. There is no job filter and no per-job channel.
- Runs recorded before this version have no job and do not count as a previous run.
See also: Telemetry (Datadog) (Datadog traces and metrics), Scheduling With Cron, Operating barca serve.
The same text is in your terminal: barca docs slack.