Webhooks allow you to trigger an HTTP request when a pact is changed, a pact is published, or a verification is published. The most common use case for webhooks is to trigger a provider build every time a pact changes, and to trigger a consumer build every time a verification is published.
Webhooks can be used in conjunction with the can-i-deploy tool (a CLI that allows you to easily check the verification status of your pacts), to allow you to fully automate the CI/CD process for all the applications that use the Pact Broker, ensuring both sides of the contract are fulfilled before deploying.
If you're reading this page and you're not sure what you're doing, what you probably need to do is to create a webhook that triggers a provider verification build when a pact is published with new content. How this works is described below in the When the consumer makes a change section. If you are using Pactflow, you can create a webhook through the UI. If you are using the OSS Pact Broker, using the create-webhook command from the Pact Broker CLI is the easiest approach. You'll find a library of commonly used webhook templates for many of the popular CI systems here.
The broker uses the following logic to determine if a pact has changed:
- If the relevant consumer version has any tags, then for each tag, check if the content is different from the previous latest version for that tag. It is 'changed' if any of the checks are true. One side effect of this is that brand new tags will trigger a pact changed event, even if the content is the same as a previous version.
- If the relevant consumer version has no tags, then check if the content has changed since the previous latest version.
This is triggered every time a pact is published, regardless of whether it has changed or not.
This is triggered every time a verification is published.
This is triggered every time a verification is published with a successful status.
This is triggered every time a verification is published with a failed status.
You can use template parameters in the request URL, body and headers to pass through metadata about the event. The most common use of this feature is to pass though the URL of the pact that has changed to the provider verification build. See this list of available parameters.
Note that if the pact content has not changed, it is "pre verified", and the provider verification portion of this diagram can be skipped.
What to do if your Pact Broker webhooks can't contact your CI because it is in a private network
If your consumer and provider builds are both within the same private network, or you share access to each other's repositories, you can achieve a similar result by either embedding the pact verification part of the provider's build into the consumer's pipeline, or having the consumer builds trigger the provider verification build directly. To speed up your builds, you can ensure that you only run this verification step when the pact has changed (rather than on every build), by using
can-i-deploy to determine if the step is necessary. eg
pact-broker can-i-deploy --pacticipant <CONSUMER> --version <CONSUMER_VERSION> --pacticipant <PROVIDER> --latest <TAG_NAME_OF_MAIN_LINE_OF_DEVELOPMENT>. Note however that duplicate results in the Pact Broker are expected and not an issue - this is simply a speed optimisation.
Consumer test job- runs unit tests, runs pact tests, publishes pact. Triggers
Consumer pact check job
Consumer pact check job- this is the point where you decide if you can deploy the consumer straight away, or if you need to wait for the pact to be verified. It checks the status of the pacts using
can-i-deployis successful, this job triggers
Consumer deploy. If it is unsuccessful, it should fail the job to provide visibility of the status of your pacts in the build pipeline. Having this as a separate job rather than bundling it in with the test or deploy jobs means that the reason for a "failure" is obvious at a glance. If you have set up a webhook to trigger the provider verification on pact changes, then you can make can-i-deploy wait for a result before continuing using the
Consumer deploy job- deploys consumer
Provider test job- your normal provider pipeline. Runs unit tests, runs pact verification tests, publishes verification results. Typically, the pacts with
prodtags would be verified during this job.
Provider pact check job- this is the point where you decide if you can deploy the application. It checks the status of the pacts using
can-i-deployis successful, this job triggers
Provider deploy. If it is unsuccessful, it should fail the job to provide visibility of the status of your pacts in the build pipeline. Having this as a separate job rather than bundling it in with the test or deploy jobs means that the reason for a "failure" is obvious at a glance.
Provider deploy job- deploys provider
You can see an example project with a Github Workflow set up as described here.
Changed pact verification job- triggered by the 'contract_content_changed' webhook, this job verifies only the changed pact, and publishes the verification results back to the broker. This pact verification job configuration will be different to the one configured as part of the main provider pipeline, and should accept the URL of the changed pact as a configurable parameter. To do this, you must use webhook template parameters to pass the URL of the changed pact through to the CI, which can then pass it in to the verification task. See the pact verification configuration documentation for your language.
You can see an example project with a "changed pact verification" Github Workflow set up as described here.
You can see an example
create-webhook command for triggering the "changed pact verification" here
contract_content_changedwebhook - triggers
Pact verification job. Note that this webhook will only be triggered if the content of the pact has changed. If it hasn't changed, then the new publication of the pact will inherit the verification from the previous publication and be "pre-verified" (or "pre-failed").
provider_verification_publishedwebhook - triggers
Consumer pact check job. This webhook will be triggered every time a verification is published. The
can-i-deploytool will need to be used in conjunction with a query to the state of your own infrastructure to let you decide whether or not you need to deploy the consumer. ie. the provider may verify the same version of the pact multiple times, invoking the webhook each time, but you only want to deploy a certain version of your consumer once.
- Debugging webhooks
- Webhook API documentation - note that there is not yet a UI for creating webhooks. If you're interested in creating one, contact us on the Pact Broker slack channel.
- Webhook template parameters
- can-i-deploy documentation - Documentation for the Pact Broker
can-i-deployCLI, which allows you to retrieve the verification results and determine whether your application is safe to deploy.
- Webhook template library - a library of useful webhook templates