Subscriptions & Alerts

Consumer teams subscribe to services they depend on. When breaking changes are detected in a new spec version, subscribers receive an email alert immediately.

How subscriptions work

A subscription is simply an email address associated with a service. Subscribers don't need a SpecVault account — the system is intentionally lightweight. You add an email, and that address receives alerts when the service's API breaks backward compatibility.

Subscriptions are per-service. If a consumer team uses three APIs, they subscribe to all three services individually. This gives producers and consumers fine-grained control over notification routing.

Adding a subscriber

From the service detail page, click Add Subscriber and enter the email address. You can add:

• Individual engineer addresses (e.g. alice@example.com)
• Team distribution lists (e.g. frontend-team@example.com)
• Slack email integrations or webhook-to-email bridges

There is no confirmation email sent to the subscriber — the admin adding the address is responsible for ensuring it's correct.

What triggers an alert

Alerts are sent only when breaking changes are detected. If a new spec version has no breaking changes — only additive changes, or no changes at all — no alert is sent. This keeps alert volume low and signal-to-noise ratio high.

Alert content

Each alert email includes:

• Service name
• New version number
• Publish date and time
• Total number of breaking changes
• Full list of breaking changes, each with HTTP method, path, and a description of what changed
• Link to the version detail page in the SpecVault dashboard

See Notifications for the full alert format and SMTP configuration.

Blast radius — who is actually affected

Detecting a breaking change is only half the job. SpecVault also tells you which consumers it breaks, instead of paging everyone subscribed.

On a service's Subscribers tab, a consumer can declare the endpoints — and optionally the specific fields — their integration calls (for example GET /orders, or GET /users field email). When a breaking change lands, SpecVault intersects it against those declarations and shows the result on the change event:

• Impacted — consumers whose declared endpoint/field is hit ("impacts payments@acme — uses GET /orders").
• Impact unknown — subscribers who haven't declared their usage. They can't be cleared, so they're shown explicitly rather than silently assumed safe.

Field-level matching is leaf-name based: declaring email matches a change to that field wherever it appears, but for deeply nested fields declare the dotted path (user.email) so a parent-object removal still attributes correctly.

Subscription management

The Subscribers tab on each service page lists all subscribers and the endpoints each has declared. Admins can remove any subscriber; each user can also manage their own subscriptions from the My Subscriptions page — toggle breaking-only vs. all changes, or unsubscribe — without needing an admin.

Pausing a service

Deactivating a service stops alerts while keeping its full history; it stays in the registry, greyed out, and can be reactivated at any time. A deactivated service still records change events — it just doesn't notify. Deleting a service is a hard delete that permanently removes it and all its versions, change events, subscribers, and dependencies.