Rules, digests and quiet hours

Rules decide what reaches which destination: at once, in the digest, or not at all. Everything here is deterministic and shows up on the event’s “why” page.

The defaults

With no rule of your own enabled, a project routes like this:

urgent and high priority events go out immediately to every enabled email and webhook destination;
everything else goes into the digest;
marketing is suppressed.

Priority comes from category and severity: an incident the vendor calls critical is urgent, a major one is high, a security advisory is high, a release is normal. GET /v1/projects/{id}/rules returns the defaults in force when using_defaults is true.

Your own rules

curl -X POST https://api.changelog.observer/v1/projects/<project_id>/rules \
  -H "Authorization: Bearer <rules:write key>" -H "Content-Type: application/json" \
  -d '{
    "name": "Page on-call for production incidents",
    "match": { "categories": ["incident"], "min_severity": "major", "environments": ["production"] },
    "mode": "immediate",
    "destination_ids": ["dst_oncall"]
  }'

match field	Meaning
`categories[]`	Any of the event categories.
`min_severity`	At least this upstream severity (minor, major, critical).
`min_priority`	At least this platform priority (low, normal, high, urgent).
`dependency_ids[]`	Only these dependencies.
`source_types[]`	Only these sources (status_page, rss, atom, github_releases, osv, json_api, email, manual).
`environments[]`	The event’s dependency must serve one of these environments. An event without a dependency never matches an environment rule.
`exclude_duplicates`	Default true: a repeat of an earlier event does not match.

An empty match matches everything. Modes are immediate, digest and suppress. When several rules match one event, suppress wins, then immediate, then digest. As soon as one rule of yours is enabled, the defaults step aside entirely, so write the whole policy you want.

The digest

One email per project gathering the digest-mode events since the last one, grouped by dependency. It goes out daily at 08:00 UTC unless the project has a schedule: {"frequency": "daily" | "weekly", "hour": "HH:MM", "timezone": "Europe/London", "weekday": 0-6} on PATCH /v1/projects/{id} (digest_schedule). GET /v1/projects/{id} shows next_digest_at. An empty digest is not sent.

Quiet hours

A window in the project’s own time zone during which nothing immediate goes out; those events wait for the digest. {"start": "22:00", "end": "07:00", "timezone": "Europe/London", "critical_override": true} on PATCH /v1/projects/{id} (quiet_hours, or null to clear). With critical_override, urgent upstream incidents still go out. Every event routed inside the window records it on its decision.

Pausing and mutes

Pause a project (paused: true): sources keep collecting, nothing is delivered, the digest waits. Resume and only new events go out.
Mute a dependency (muted_until on the dependency, or the bulk actions on incidents): its new events go to the digest only until the time passes.
Snooze an incident (muted_until on the incident): it leaves “open for us” until then.

Per-dependency preferences

What a project does not want from one dependency at all: {"ignore_categories": ["announcement"], "ignore_sources": ["rss"], "ignore_senders": ["news@vendor.example"], "min_severity": "major"} on PATCH …/dependencies/{depId}. Matching events are stored as suppressed with the preference named on them, and never delivered. GET …/dependencies/{depId}/preference-suggestions says what the record supports ignoring, from your feedback, suppressed mail and volume. Send the preferences object whole.

Usage caps

Meters are per workspace and per calendar month: distinct dependencies, inbound mail, events processed, webhook deliveries, stored raw mail. When any processing cap is reached, events are still stored and only urgent upstream incidents are delivered until the month rolls over. GET /v1/usage shows the meters and whether a cap is in force.