Specifying third‑party integrations: templates and vendor change‑control gates for product teams

A payment provider quietly deprecates a webhook field. A shipping API adds a mandatory header. An identity vendor rotates a token format on a Tuesday with 14 days notice buried in a changelog nobody subscribed to. None of these are exotic events — they're the normal operating conditions of building on top of other people's systems, and most requirement docs pretend they don't exist.

That's the gap this piece is about. Not "how to integrate with a third party" — you already know how to read an API doc. The problem is that integration requirements are usually written once, at kickoff, and never mapped to the fact that the thing you depend on is owned by someone who can change it without asking you. So when the change comes, there's no owner, no gate, no verification step. Just a broken checkout at 9pm and a Slack channel full of question marks.

Where third party integration requirements actually break

The failure almost never happens at integration time. Integration time is when everyone is paying attention. QA runs the happy path, someone tests a couple of edge cases, the demo works, everyone moves on.

The break happens six weeks later, when:

1. 1
   The vendor pushes a "non-breaking" change that turns out to be breaking for your specific usage
2. 2
   Your requirement doc says "integrate with Stripe" instead of specifying which API version, which fields, and what happens when they change
3. 3
   Nobody owns the vendor relationship, so nobody is subscribed to their changelog
4. 4
   The integration passed release once, so it's treated as done — not as a living dependency

This is what happens when a team treats a third-party integration like an internal component. Internal components change on your schedule. Third-party ones don't. The requirement needs to encode that difference explicitly, or the difference gets discovered in production.

A typical example: a mid-size SaaS billing feature integrated with a tax-calculation API. The original requirement was a single line — "calculate sales tax via [vendor] API on invoice generation." Eleven months later, the vendor changed how they returned exemption codes. Nothing in the requirement said which fields were load-bearing, so nobody flagged the change. Around 400 invoices went out with wrong exemptions before finance caught it in a reconciliation. The fix took two days. The cleanup took closer to three weeks.

The requirement template that closes the gap

Most integration requirements are missing four things: version pinning, a field-level contract, an SLA expectation, and a named change protocol. Here's the structure that actually holds up.

The field contract is the part teams skip, and it's the part that saves you. "We call the geocoding API" tells you nothing. "We depend on results[0].geometry.location.lat, .lng, and formattedaddress; we ignore everything else" tells you exactly what a vendor change can and can't hurt. When the vendor's changelog says "we're deprecating formattedaddress," you know in ten seconds whether you care.

SLA template — fill these in per integration

1. 1
   Latency budget

   p95 under X ms; alert at Y ms

2. 2
   Availability target

   vendor's stated SLA vs. what your feature actually needs

3. 3
   Rate limits

   documented ceiling, your typical peak, headroom margin

4. 4
   Error handling

   what your system does on 429, 5xx, and timeout — separately

5. 5
   Degraded mode

   what the user sees when the vendor is slow but not down

Those last two rows matter more than the uptime number. Most integrations have a plan for "vendor is down" and no plan for "vendor is slow." Slow is worse, because it doesn't trip your outage alerts — it just quietly holds threads open and degrades the whole feature.

Breaking-change protocol — the part with a name attached

1. 1
   Named owner for the vendor relationship (not "the team" — a role or person)
2. 2
   Change intake

   where vendor notices land (changelog subscription, status page, account rep email)

3. 3
   Severity classes

   cosmetic / non-breaking / breaking / security — with an example of each for this vendor

4. 4
   Notice window expectation

   what you need from them, and what you do if they don't give it

5. 5
   Fallback behavior

   documented, per severity

The severity examples are the trick. A generic severity scale is useless. "For our shipping vendor, a breaking change means any change to the rate-quote response schema; a non-breaking change means a new optional field" — that's specific enough that a junior dev can classify an incoming changelog entry without asking anyone.

The goal isn't an elaborate governance doc. It's a few concrete definitions that remove ambiguity in the moment when someone's staring at a changelog entry at 4pm on a Friday.

Owner-triggered verification instead of set-and-forget

The pattern that separates teams who get surprised from teams who don't: verification isn't automatic-only, and it isn't calendar-based. It's triggered by an owner at defined points, tied to your release cadence.

Why owner-triggered rather than fully automated? Because contract tests catch schema breaks, but they don't catch semantic breaks — where the field still exists but now means something slightly different. The exemption-code example above would have passed every contract test. The response was still valid JSON with the right shape. The meaning changed. Only a human re-reading the field contract against the vendor's release notes catches that.

A practical verification cadence:

1. 1
   Every release that touches the integration

   owner re-confirms the field contract still matches reality

2. 2
   Every vendor changelog entry

   owner classifies severity within the notice window

3. 3
   Quarterly, even with no changes

   owner re-validates SLA numbers against actual observed metrics, because drift is silent

The quarterly one catches degradation nobody announced. Vendors don't send a changelog when their p95 latency creeps from 120ms to 340ms. You find that by looking.

Gating vendor changes into your release cadence

Most teams treat vendor changes as reactive incidents. They should be a gate in your normal flow — the same way a failing test is a gate.

The workflow, in plain terms:

1. 1
   A vendor change is detected (changelog, alert, or verification step flags drift).
2. 2
   The owner classifies it against the breaking-change protocol severity classes.
3. 3
   If it's cosmetic or non-breaking → log it, attach to the integration requirement, no gate.
4. 4
   If it's breaking or security → it becomes a gating item on the next release that touches that integration. The release doesn't ship until the requirement, the field contract, and the verification step are updated and re-checked.
5. 5
   The updated requirement carries a note

   what changed, when, who verified.

A simple visual of the gate helps teams remember where vendor changes belong in the flow.

The reason to bolt this onto release cadence rather than running a separate "vendor change process" is straightforward — separate processes get abandoned. A gate that lives inside the flow people already follow gets followed. If your release checklist already blocks on failing tests and missing acceptance criteria, adding "no unresolved breaking vendor changes" is a small addition, not a new ritual.

This connects directly to how you'd already be handling contract-based dependencies internally. If you've worked through the approach in requirement patterns for microservices: contracts, owners and integration acceptance criteria, the vendor version is the same discipline pointed outward — except you don't control the other side of the contract, so the gate matters even more. And when integrations cross multiple teams, the handoff and boundary rules in the program-level requirements operating model tell you who owns the gate when two teams both depend on the same vendor.

Real scenario: a logistics startup and a carrier API

A logistics startup, around 30 people, ran shipment tracking through three carrier APIs. Their integration requirements were the usual one-liners. When one carrier changed a status-code mapping — "in transit" split into two sub-states — the carrier labeled it non-breaking. For the startup, it was breaking. Their customer-facing status page mapped the old single code to a specific message.

Before they put any structure around this: no owner, no field contract, no gate. The change landed on a Thursday. Customers started hitting the status page and seeing a blank state for the new sub-code. Support ticket volume roughly doubled for about five days. Engineering spent a day and a half tracing it back to the carrier changelog, because nobody had connected the dots.

After they implemented the template and gate, each carrier integration got a named owner, a field-level contract listing exactly which status codes drove which UI messages, and a verification step on every release touching tracking. The next time a carrier added codes — about four months later — the owner caught it in the changelog, classified it as breaking, and it became a gating item on the next release. The status page was updated before the change went live. Zero related tickets.

The difference wasn't smarter engineers. It was that "the vendor might change something" moved from an unspoken assumption into an explicit, owned, gated part of the requirement.

When this level of rigor makes sense

Not every integration needs the full treatment. Over-governing a low-stakes integration wastes time.

This makes sense when:

1. 1
   The integration is in a revenue or compliance path (payments, tax, shipping, identity)
2. 2
   A silent semantic change would reach customers before you noticed
3. 3
   The vendor has a history of loosely-communicated changes
4. 4
   Multiple teams depend on the same integration

This is overkill when:

1. 1
   It's an internal-only integration with a vendor you can pin and freeze
2. 2
   The blast radius of a failure is a dev-tool dashboard, not a customer
3. 3
   You call the API once a quarter and manually check the result anyway

A two-person team with one non-critical integration probably doesn't need a formal severity protocol — the overhead will cost more than the occasional breakage. For them, a single field contract and a changelog subscription is enough. The full gate earns its keep once you have several integrations, several people, and a release cadence that already has checkpoints to hang it on.

Where tooling helps, and where it doesn't

You can run all of this in whatever system already holds your requirements — the templates are just structured sections, and the gate is a checklist item on your release. The one thing worth centralizing is the link between the field contract, the vendor's changelog entry, and the verification record, so that when someone asks "why did we change this mapping in March," the answer is one click away instead of a Slack archaeology dig.

A requirements platform that lets you attach vendor-change notes to a specific requirement and trace it to the release that resolved it turns those questions into quick lookups. But the discipline is what matters. The tool just keeps you honest about doing it.

The one thing to take away

Third party integration requirements fail not because they're complex, but because they're written as if the other side is frozen. It isn't.

Pin the version, list the fields you actually depend on, name an owner, define what a breaking change means for your usage, and put a gate on your release that a breaking change can't slip past. Do that, and vendor surprises become routine handling instead of Thursday-night fire drills. Skip it, and you'll keep finding out about vendor changes the same way everyone else does — from your customers.

Third party integration requirements fail not because they're complex, but because they're written as if the other side is frozen. It isn't.

Pin the version, list the fields you actually depend on, name an owner, define what a breaking change means for your usage, and put a gate on your release that a breaking change can't slip past. Do that, and vendor surprises become routine handling instead of Thursday-night fire drills. Skip it, and you'll keep finding out about vendor changes the same way everyone else does — from your customers.