Provider API change breaks contract: pre-release and first 30 minutes checklists

A third-party API changes a field or behaviour and the integration fails.

The pre-release checklist maps each item to a test class from the incident page. The first-30-minutes checklist covers detection, containment, the rollback decision and customer communication.

8 pre-release items · 7 first-30-minutes items · verified 2026-10-21

Pre-release checklist

PR-01Run the integration suite against the provider sandbox on a daily schedule, not only on commits, and alert when a previously passing test fails with no code change. integration
PR-02Run the context permission check client against a stub that returns 404 with an explanation body and confirm the job fails with a logged upstream error instead of hanging in the queue. integration
PR-03Delete a speculative branch in the provider sandbox and confirm a new pull request opens for the same head branch. integration
PR-04Issue a token through a custom domain in a test tenant and confirm a resource server that validates iss still accepts it after the release. integration
PR-05Before releasing a change to the end of call webhook payload, run every published consumer contract and fail the release when any field's type set changes. contract
PR-06Run the consumer contract for each upstream endpoint against the provider's announced new path before the brownout date. contract
PR-07Schedule a production check that receives the end of call webhook into a strictly typed consumer and alerts on any parse error. synthetic
PR-08Schedule a production check that starts a job reading a context and alerts if the job moves to Failed. synthetic

First 30 minutes

FM-01Check whether the failures began without a deploy of the own service, and compare the start time with the provider's changelog and deprecation notices.
FM-02Search logs for upstream responses with new status codes or bodies, such as 404 responses carrying explanation text.
FM-03Pause or drain queued jobs that call the failing upstream path so the queue stops growing.
FM-04Decide whether to repoint the request to the provider's new path or ship a workaround that performs the step the provider no longer performs.
FM-05If the own release changed a payload field type or token claim, decide between reverting the output and asking customers to change their validation.
FM-06Open a ticket with the provider's support and attach request and response samples from before and after the change.
FM-07Post a status update that names the affected integration path and the affected customer segment, such as custom domain users or strict type consumers.

Download the checklist

Pre-release checklist (Markdown)1.7 KB · v1.0.0
First 30 minutes checklist (Markdown)1.3 KB · v1.0.0

Only in this checklist

Every test class in this checklist also appears in at least one sibling checklist in the group; the item texts differ: Run the integration suite against the provider sandbox on a daily schedule, not only on commits, and alert when a previously passing test fails with no code change.

Questions

What should be checked before a release to prevent Provider API change breaks contract?

8 pre-release items, PR-01 to PR-08. PR-01: Run the integration suite against the provider sandbox on a daily schedule, not only on commits, and alert when a previously passing test fails with no code change.

Is there a rollback plan for Provider API change breaks contract?

The first-30-minutes checklist has 7 items. FM-01: Check whether the failures began without a deploy of the own service, and compare the start time with the provider's changelog and deprecation notices.

What should a team do in the first 30 minutes after Provider API change breaks contract is detected?

Is a Provider API change breaks contract checklist still needed if deployment is automated?

Yes. Automation runs the steps; the checklist names what the tests must cover: integration tests, contract tests and synthetic monitoring.

Which pipeline stages does the Provider API change breaks contract checklist cover?

The pre-release items map to the pre-deploy, pre-merge and post-deploy stages.

In what formats can the Provider API change breaks contract checklist be downloaded?

Both checklists download as Markdown files: /downloads/provider-api-change-breaks-contract-pre-release.md and /downloads/provider-api-change-breaks-contract-first-30-minutes.md, licensed CC BY 4.0.