How does a Pact Broker webhook trigger a provider's verification build, and what does that cost?
answer
- The broker can push, not only store
- An event plus a stored HTTP request
- Content-changed, not every publish
- Someone else's push spends your build minutes
- The durable artefact is the verification result
basics
~20 sA webhook subscribes to broker events such as contract content changing, and posts a request to the provider's CI to start a verification build for that pact URL. It buys fast feedback and costs provider build capacity and cross-team coupling.
solid answer
~50 sA Pact Broker webhook is a stored HTTP request the broker sends when an event fires. The useful events are contract-side — most commonly `contract_content_changed`, which fires only when a published pact differs from the previous one, and `contract_requiring_verification_published` — and the request body can interpolate broker template parameters such as `${pactbroker.pactUrl}`, `${pactbroker.consumerName}` and `${pactbroker.consumerVersionNumber}`. The target is the provider CI's build-trigger API; the triggered build verifies that one pact URL and publishes results back, which is what later fills the verification matrix cell. The gain is feedback time: the consumer team learns within minutes rather than at the provider's next scheduled run. The costs are real — provider build minutes consumed by another team's pushes, a provider build that can go red because of a consumer change, and stored credentials for triggering builds across team boundaries.
code
json · 13 lines{
"events": [ { "name": "contract_content_changed" } ],
"request": {
"method": "POST",
"url": "https://ci.example.internal/pipelines/tram-telemetry/verify",
"headers": { "Content-Type": "application/json" },
"body": {
"pactUrl": "${pactbroker.pactUrl}",
"consumer": "${pactbroker.consumerName}",
"consumerVersion": "${pactbroker.consumerVersionNumber}"
}
}
}go deeper
Recall that the broker can call out to another system when something changes, so a provider's tests can start automatically after a consumer publishes a new contract.
Be ready to describe the mechanism: an event subscription, a stored HTTP request with interpolated values such as the pact URL, and a provider build that verifies and publishes results back.
An interviewer expects the tradeoff and the debugging path: content-changed versus every publish, provider build volume owned by other teams, and the three links to check when feedback stops arriving.
Own whether provider teams are obliged to accept externally triggered builds at all, how that capacity is budgeted, and how a consumer team is prevented from breaking a provider's build signal.
## The mechanism Without webhooks, contract feedback is pull-based: the provider verifies pacts whenever its own pipeline happens to run. A consumer that publishes a new expectation on Monday afternoon might not learn whether the provider satisfies it until the provider's next build. Webhooks close that loop by making the broker push. A webhook in the Pact Broker is a stored HTTP request plus the events that should send it. The request is fully specified — method, URL, headers, body — and the body may interpolate template parameters the broker substitutes at send time. The ones you reach for are `${pactbroker.pactUrl}` (the exact contract to verify), `${pactbroker.consumerName}`, `${pactbroker.providerName}` and `${pactbroker.consumerVersionNumber}`. The target is usually the provider CI system's API for starting a build, with those values passed through as build parameters. The triggered build then does the provider side of the job: fetch that specific pact, replay its interactions against the provider, and publish the verification result back to the broker. Only that last step matters to the rest of the system — the webhook is a delivery mechanism for feedback, and the durable artefact is still the recorded verification result. ## Choosing the event Event choice is the main volume control, and it is worth being precise about the two that matter: - **`contract_content_changed`** fires when a publish results in contract content that differs from what was there before. A consumer that pushes eleven times a day but only changes the pact twice triggers two provider builds, not eleven. - **`contract_requiring_verification_published`** fires when a pact is published that the provider has not yet verified, which is the more direct expression of "there is work for you". There are also verification-side events — results being published, and success and failure variants — which are typically wired to notifications or to a status update on the consumer's commit rather than to another build. Subscribing to a publish-shaped event with no content-change condition is how organisations end up with a provider pipeline saturated by the busiest consumer's branch pushes. ## What it buys | Property | Without webhooks | With webhooks | |---|---|---| | Feedback latency | Until the provider's next build | Minutes | | Who notices a break | Whoever reads the provider build later | The consumer, on the change that caused it | | Matrix freshness at release time | Often unknown, forcing retries | Usually already resolved | | Provider build volume | Its own commits only | Plus consumer contract changes | The third row is the underrated one. A deployability check that keeps hitting unknown results because verification has not run yet is a check that teams learn to retry, then to ignore. Webhook-driven verification keeps the matrix filled in, so the gate is usually answering from facts rather than waiting for them. ## What it costs 1. **Build capacity.** Provider CI now runs work initiated by other teams. On a fleet of consumers this can be a large fraction of the provider's pipeline usage, and it is not visible in the provider's own commit history. 2. **Cross-team coupling in the worst place — the build signal.** A new consumer expectation can turn the provider's build red for a contract the provider never agreed to. The standard mitigation is to let a not-yet-verified expectation be recorded without failing the provider's build, so the provider team opts in deliberately rather than being conscripted. 3. **Credentials and blast radius.** The broker holds a token that can start builds in the provider's CI. That is a secret with real power, and it should be scoped to triggering one pipeline. 4. **Debuggability.** When feedback stops arriving, the failure could be the event never firing, the request failing, or the triggered build never publishing results. The broker keeps a log of webhook executions and their responses, which is the first place to look; the second is whether the triggered build published a result at all. ## A sensible default For a depot-fleet estate with a handful of providers and many consumers, the arrangement that holds up is: subscribe on contract content changing, target one narrowly scoped trigger endpoint per provider, pass the pact URL through so the build verifies exactly one contract rather than sweeping everything, publish results unconditionally, and keep new consumers' expectations from being able to fail the provider build until the provider team accepts them. That gives fast feedback where it changes behaviour, and keeps the provider team's pipeline theirs.
- Why subscribe to a contract-content-changed event rather than to every pact publish?Because most consumer builds republish an identical contract. The content-changed event fires only when the published pact differs from what the broker already held, so a consumer pushing a dozen times a day triggers provider verification only on the pushes that actually changed an expectation. Subscribing to every publish makes the provider's pipeline a function of the busiest consumer's commit rate.
- Webhook-triggered verifications stopped arriving. Where do you look first?Split the chain into three links. Check the broker's record of webhook executions and their response codes to see whether the request fired and was accepted. If it fired, check whether the provider build actually started and completed. If it completed, check whether it published a verification result — a build that verifies and never reports leaves the matrix cell empty, which looks identical from the consumer's side.
saying these in an interview costs you the question
- Thinks the broker runs the verification itself on the event
- Subscribes to every publish and floods the provider pipeline
- Ignores that another team's push now spends provider build minutes
- Cannot say what the triggered build must publish back
- Stores a broadly scoped CI token in the webhook