Alerts
Alerts follow the log: when something a person needs to know is written there, watchdep tells the people who asked to hear about it, by email, in a digest, on screen, and through the workspace webhook. Each person chooses how they hear per level; a few things are always told at once, whatever anyone chose.
What raises an alert
| Event | Alert | Level used |
|---|---|---|
| A finding is new | new | the finding’s level |
| A finding reopens (reappeared after fixed or withdrawn; a new place or path after a decision; an acceptance expired) | reopened, told as new | the finding’s level |
| A finding’s level goes up | escalation | the new level |
| A malicious release is found on a branch that is not production | malicious release on a branch | severe |
| A source has no good sync for 24 hours, and when it recovers | source stalled, source recovered | (not a finding) |
- A level going down is quiet. So is a decision, except on the webhook when “Also every state change” is ticked (below).
- Never twice. Each finding alerts each person once, plus once per escalation, plus once each time it reopens. However often the checks run, the same alert is never made twice, and a sent alert is never sent again.
- Only what really happened. Alerts are planned only after the change is saved, so a change that was rolled back never alerts anyone.
- Development-only findings follow the level they are ranked at: a development-only critical is high, and goes where you send high. See Levels and lanes.
- Early warnings: a severe early warning is always told immediately; one with no level goes to the daily digest of everyone who gets any alerts, never immediately.
My alerts
Each person chooses, per level, how they hear in each workspace (Settings, My alerts):
| Delivery | Meaning |
|---|---|
| Immediately | one email per finding, as soon as it is known |
| Daily digest | one email a day, at the chosen hour: one entry per finding, at its current level; a finding fixed or decided before then is left out |
| Weekly digest | one email a week, on the chosen day at the chosen hour |
| Screen only | no email; the finding is on the screens |
The defaults:
| Level | Delivery |
|---|---|
| Severe | Immediately |
| High | Daily digest |
| Medium | Weekly digest |
| Low | Screen only |
Digests go at 08:00, the weekly one on Mondays, in the time zone of the owner’s alert settings (UTC for the owner by default). Each person can change their hours, day and time zone: hours run from 00 to 23, and the time zone must be a known one. A person may narrow their alerts to chosen applications of the workspace; none ticked means all.
Always told, whatever a person chose:
- A malicious release is told immediately to everyone in the workspace, regardless of their level settings and application narrowing. The remedy is to remove the version now.
- A malicious release on another branch is told to everyone immediately too, once per inventory and advisory, because its install scripts already ran on a developer’s machine or in CI.
- A stalled source is told to the workspace’s owners and admins, once per stall, and its recovery once. Silence from a source is not safety. A source that has never run is not a stall.
Email goes out from the hosted service’s own address.
- An immediate alert has a subject such as “[watchdep] Severe: rack: Shell escape in Rack” (or “Escalated to severe: …”, “Malicious release: …”, “Source stalled …”). The body names the level, the id, the application, the summary, the labels and why it has that level, the first dependency path (“api > sidekiq > rack”), the fix (“Fix: upgrade rack to 2.2.3.1” or “No fixed version published”) and a link to the finding.
- A digest (“[watchdep] Daily digest for Prospec360 team: 3 findings”) lists each finding the same way, loudest first, and is sent only when something is waiting. On the weekly day, the daily digest also carries the week’s waiting weekly alerts.
- Every email is plain text and HTML, with no images and nothing that tracks.
- A failed send is recorded on the alert with its error and retried with growing waits, five attempts in all; a digest retries at the person’s next digest hour.
- No email settings, no silent drop. On a copy with no SMTP settings, every email alert is recorded as not sent with the reason “this copy has no email settings”, shown on the finding page and in My alerts.
The workspace webhook
One webhook per workspace, managed by owners and admins (Settings, Webhook): its URL, the lowest level sent (high by default), and whether it is active. Point it at a Slack or Microsoft Teams incoming webhook, or any URL that accepts a JSON post. Slack and Teams show the message’s text as it is.
- Every alert at or above the chosen level is posted once, immediately, as JSON. Malicious findings, malicious releases on branches, and source health are always sent while the webhook is active.
- Events:
finding.new,finding.escalated,finding.reopened,branch.malicious,source.stalled,source.recovered,test, andfinding.state_changedwhen “Also every state change” is ticked. - Also every state change (off by default): every state change of a finding by a person, a host application, an agent or the CLI (acknowledged, accepted, not affected, fix pull request open, fix merged, fixed, reopened by expiry) posts one
finding.state_changed, whatever its level, with the change’sfrom,to,whoandreason. A host application can use it to refresh its own screen. A finding’s first appearance isfinding.new, not a state change. - Send a test posts a
testevent at once and shows the status it answered, or only that it could not be reached or did not answer within 10 seconds. - A post that errors, or answers anything but a 2xx status, is recorded (last delivery, status, error) and retried, five attempts in all.
A shortened example:
{
"event": "finding.new",
"text": "Severe: rack: Shell escape in Rack (CVE-2022-30123) in Prospec360. https://watchdep.example.com/findings/12",
"workspace": "Prospec360 team",
"sent_at": "2026-11-12T13:40:00Z",
"finding": {
"id": 12,
"primary_id": "CVE-2022-30123",
"ids": ["CVE-2022-30123", "GHSA-wq4h-7r42-5hrr"],
"level": "severe",
"labels": ["provisional"],
"application": "Prospec360",
"scope": "production",
"state": "new",
"places": [{ "part": "api", "ecosystem": "RubyGems", "name": "rack", "version": "2.2.3",
"file": "Gemfile.lock", "paths": [["sidekiq", "rack"]], "fix": "2.2.3.1" }]
},
"fix": "2.2.3.1"
}
Checking the signature
Each post carries three headers: X-Watchdep-Event, X-Watchdep-Timestamp (Unix seconds) and X-Watchdep-Signature: sha256=<hex>. The signature is the HMAC-SHA256 of the timestamp, a full stop, and the raw body, keyed with the webhook’s secret. Your receiver recomputes it and rejects a mismatch or an old timestamp. For example, in a shell:
printf '%s.%s' "$timestamp" "$body" | openssl dgst -sha256 -hmac "$secret"
The secret starts whsec_. It is made when the webhook is added and whenever someone asks for a new one, shown once, and stored encrypted.
Private networks
Before each post, the webhook’s host is looked up once, and every address it gives is checked: private, loopback, link-local and every other reserved range, in IPv4 and IPv6, including an IPv4 address carried inside an IPv6 one. The post then goes to the checked address itself, so a name cannot answer differently a moment later, and redirects are never followed. Such an address is refused unless the owner ticked “Allow private network addresses”. Admins cannot change that setting. On the hosted service such an address is always refused, whatever was ticked.
On screen
- A finding’s page has Who is told: each alert by kind, channel, delivery and state, for example “D. Kim, by email immediately, 10 Nov 13:40”, “3 people, in the daily digest, waiting” or “The webhook, posted immediately”. Failures are in deep orange with the error. With none: “Nobody yet: everyone’s settings put medium on screen only”.
- The log records, once per event, who was told: “Told: 1 person immediately by email and 2 in their daily digest and the webhook”, by the system.
- The status bar shows the alerts sent today and, in deep orange, how many failed in the last 24 hours.