Provider verification and the broker: replaying the consumer''''s expectations against the real service

Priya’s checkout-web team published a pact: “when I GET /prices/42, I read amount_cents (a number) and currency (a string).” The contract now exists. But a contract no one checks is just a wish. Sam owns the pricing service, and last sprint he renamed amount_cents to unit_amount — a clean refactor, all of pricing’s own tests green, deployed Friday. On Monday checkout-web rendered NaN on every product page because the field it parses had silently vanished. The pact described exactly the breakage that shipped, and nothing replayed it against Sam’s real service before he deployed. The recording was never played back. That playback — sending each recorded request at the actual running provider and checking the response still honours what the consumer reads — is provider verification, and the place that stores the pacts and the verification results so the two teams never have to coordinate by hand is the broker.

Verification is replay, not re-reading

The pact file is a list of concrete interactions: request, expected response, and the provider state each one assumes. Provider verification is mechanical: a Pact verifier takes that list and, for each interaction, sends the recorded request to the real, running provider and compares the actual response against the expected one. No mock is involved on the provider side — the request hits the genuine routing, controllers, serializers, and (with state set up) the genuine data layer. If checkout-web’s pact says GET /prices/42 should return a body containing amount_cents, the verifier fires that exact request at the booted pricing service and inspects what comes back.

The comparison is deliberately asymmetric, and this is the property that makes the gate stable. The verifier checks that the actual response contains at least the data the consumer described — the minimal expected response. Sam can add ten new fields to /prices/42 and verification stays green, because the consumer never asserted their absence. But if he renames amount_cents, the field the consumer reads is gone, the actual response no longer contains the minimal expected shape, and verification fails before he deploys. The contract trips on exactly the change that would break a real consumer and stays silent on everything else, which is the same precision the consumer-driven recording bought you, now enforced from the provider’s side.

Provider states are the subtle hard part

An interaction like “GET /prices/42 returns 200 with a price body” is only satisfiable if price 42 actually exists in the provider when the request is replayed. The consumer recorded this precondition as a provider state — a string in the given clause, e.g. "a price with id 42 exists", the Pact equivalent of Cucumber’s Given step: put the system in a known state before the interaction runs. Verification is the moment that string has to be turned into real data.

So the provider must register state handlers: code that, for each named state, sets up the data the interaction needs. Before replaying each interaction, the verifier invokes the matching handler (often by POSTing { "consumer": "...", "state": "..." } to a test-only state-change endpoint), the handler inserts price 42 into the provider’s data store, then the request is sent. Two rules make this work and are easy to get wrong. First, each interaction is verified in isolation — no state carries over from the previous one, so every handler must establish its full precondition from scratch and ideally tear down after. Second, the handler sets up data, not the response: it makes the interaction satisfiable, but the real provider code still produces the response, which is the whole point. This is where verification quietly gets expensive — every distinct given string the consumers wrote becomes a state handler the provider team must implement and maintain, and a missing or wrong handler fails verification not because the contract is broken but because the precondition was never met.

The broker is the system of record between two pipelines

Verification needs two artifacts to meet: the consumer’s pact and the provider’s pass/fail result. The naive way to make them meet is to wire the consumer’s CI to trigger the provider’s build directly — but that re-couples the two pipelines you went to contract testing to decouple. The Pact Broker (open-source) / PactFlow (hosted) is the exchange that breaks the coupling. The consumer publishes its pact to the broker, tagged with its version and branch, and walks away. Independently, the provider’s CI pulls the relevant pacts from the broker, runs verification, and publishes the results back. Neither pipeline calls the other; the broker is the shared, asynchronous system of record holding every pact and every verification result.

The broker can also push. A webhook fires on broker events — most importantly contract_requiring_verification_published (which superseded contract_content_changed in broker 2.82.0) — to trigger the provider’s verification build the moment a new or changed pact lands, passing templated parameters like ${pactbroker.pactUrl} and ${pactbroker.providerVersionNumber} so the provider build knows exactly what to verify. The result of all this is the verification results matrix: a grid of which consumer versions have been verified against which provider versions. That matrix is what the can-i-deploy tool queries before a release — “is the version of pricing I’m about to ship verified against the version of checkout-web already in production?” — so each pacticipant (Pact’s word for an app in a contract) can deploy on its own schedule, gated by recorded results rather than by a human checking with the other team.