See provider changes coming

Most breaking changes are announced before they land. The announcement is a header on every response, or a new version of an OpenAPI document, and nobody is reading either. This page walks one announced change from the provider's notice to a planned release, with nothing broken along the way.

The scenario

Your billing service calls a payments provider to retrieve charges. The provider decides to remove source from the charge object in its next API version and to retire the version you are pinned to on 1 March 2027.

It announces this the way providers do. From October, every response to your call carries:

HTTP/1.1 200 OKStripe-Version: 2026-10-28Deprecation: trueSunset: Mon, 01 Mar 2027 00:00:00 GMT

And its published OpenAPI document gains a new version in which the charge schema has no source.

Your code reads the body and ignores the headers. Nothing fails. Without a reader, the first sign is 1 March.

What the collector sends

The collector reads the three headers on your outbound call and sends what they say, not the headers. The part of the envelope that carries it, with the other fields left out:

{  "envelopeVersion": "0.7",  "transport": {    "method": "GET",    "routeTemplate": "/v1/charges/{}",    "displayRouteTemplate": "/v1/charges/:chargeId",    "statusCode": 200,    "deprecation": {      "deprecated": true,      "sunsetAt": "2027-03-01T00:00:00.000Z",      "apiVersion": "2026-10-28"    }  }}

A date and a version label. Every other header, including Authorization and Set-Cookie, is discarded in your process. A header value that does not parse as a date or a short version label is discarded too. With observeFetch this needs no code; with observeCall it reads the headers from where common clients keep them.

What Seamward shows you

Two advisories open on the connection, apart from its incidents:

The second lists the change itself: $.source, removed from the 200 response, between published versions 2026-10 and 2026-11. It is raised only because your connection called that operation in the last 30 days. The other operations in the document that changed, and that you do not call, raise nothing.

The connection's Provider notices card shows the API version in use and the earliest end date across its operations.

Watch the published contract

On the connection's Overview, under Provider notices, enter the address of the provider's OpenAPI document. Seamward fetches it within a few minutes for a baseline, then once a day.

Watching a published contract has the size limits and what happens when a fetch fails.

Plan the change

1. Open Advisories. The list is ordered by date, soonest first.
2. Acknowledge the notice once the work is scheduled. It stays in the list with its countdown.
3. Subscribe an alert destination to advisory.opened. Your team is told when an advisory opens and again when its date is within 30 days.
4. Ask your coding agent to plan the change: list_advisories gives it the operation, the date and the changed fields through MCP.

If the provider moves the date, the advisory reopens with the new one.

Operating boundaries

• An advisory never opens an incident and never proposes a repair. If the traffic does change, drift detection reports it from what was observed.
• Seamward reports the provider's date. It cannot confirm the provider will act on it.
• There is no list of providers Seamward watches for you. A document is watched when your team gives its address.
• Nothing is shared between workspaces. Each advisory comes from your own traffic or your own watched document.
• Connections fed only by OpenTelemetry traces raise no deprecation notices, because a span carries no response headers.

Next steps

• Advisories: both kinds, and what reopens one.
• Collector reference: where the headers are read from.
• Contract registry: declare what you expect alongside what the provider publishes.