Skip to main content

Webhooks template library

Please feel free add any that you think might be useful to others.

Triggering Builds

GitHub - trigger build

Trigger a build in GitHub using the repository_dispatch event.

{
"events": [{
"name": "contract_requiring_verification_published"
}],
"request": {
"method": "POST",
"url": "https://api.github.com/repos/<organisation>/<repository>/dispatches",
"headers": {
"Content-Type": "application/json",
"Accept": "application/vnd.github.everest-preview+json",
"Authorization": "Bearer <YOUR_GITHUB_TOKEN>"
},
"body": {
"event_type": "contract_requiring_verification_published",
"client_payload": {
"pact_url": "${pactbroker.pactUrl}",
"sha": "${pactbroker.providerVersionNumber}",
"branch": "${pactbroker.providerVersionBranch}",
"message": "Verify changed pact for ${pactbroker.consumerName} version ${pactbroker.consumerVersionNumber} branch ${pactbroker.consumerVersionBranch} by ${pactbroker.providerVersionNumber} (${pactbroker.providerVersionDescriptions})"
}
}
}
}

Ref:

Using the pact_changed event (superseded)

info

We recommend using the contract_requiring_verification_published

The following templates can be updated for support by checking this short three step guide

We would welcome a pull-request to update any of the below webhooks, to the section above.

GitHub - trigger build

Trigger a build in GitHub using the repository_dispatch event.

{
"events": [{
"name": "contract_content_changed"
}],
"request": {
"method": "POST",
"url": "https://api.github.com/repos/<organisation>/<repository>/dispatches",
"headers": {
"Content-Type": "application/json",
"Accept": "application/vnd.github.everest-preview+json",
"Authorization": "Bearer <YOUR_GITHUB_TOKEN>"
},
"body": {
"event_type": "pact_changed",
"client_payload": {
"pact_url": "${pactbroker.pactUrl}"
}
}
}
}

Ref:

Travis - trigger build

{
"events": [{
"name": "contract_content_changed"
}],
"request": {
"method": "POST",
"url": "https://api.travis-ci.org/repo/<organization>%2F<project>/requests",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Travis-API-Version": "3",
"Authorization": "token TOKEN"
},
"body": {
"request": {
"message": "Triggered by changed pact for ${pactbroker.consumerName} version ${pactbroker.consumerVersionNumber}",
"branch":"master",
"config": {
"env": {
"global": [
"PACT_URL=${pactbroker.pactUrl}"
]
}
}
}
}
}
}

Ref:

Bamboo - trigger build

{
"request": {
"method": "POST",
"url": "http://master.ci.my.domain:8085/rest/api/latest/queue/SOME-PROJECT?os_authType=basic?bamboo.variable.pact-url=${pactbroker.pactUrl}",
"username": "username",
"password": "password",
"headers": {
"Accept": "application/json"
}
}
}

Ref:

Azure DevOps - trigger build

The auth token is created by encoding your PAT and username. See Azure DevOps: Use personal access tokens for more details.

{
"request": {
"method": "POST",
"url": "https://<instance>/<organization>/<project>/_apis/pipelines/<pipelineId>/runs?api-version=6.0-preview.1",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Basic TOKEN"
},
"body": {
"resources": {
"repositories": {
"self": {
"refName": "refs/heads/master"
}
}
},
//Optional: used to send parameters to your pipeline
"templateParameters": {
"myParameter": "value"
}
}
}
}

Ref:

CircleCI - trigger workflow build

N.B - currently need to use a personal API token (ideally for a machine user)

{
"events": [
{
"name": "contract_content_changed"
}
],
"request": {
"method": "POST",
"url": "https://circleci.com/api/v1.1/project/<VCS>/<ORG>/<REPO>/build?circle-token=****",
"headers": {
"Content-Type": "application/json"
},
"body": {
"branch": "<BRANCH>"
}
}
}

Bitbucket - trigger pipeline run

Run the default pipeline for a branch, for the changed pact:

{
"events": [{
"name": "contract_content_changed"
}],
"request": {
"method": "POST",
"url": "https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pipelines/",
"headers": {
"Content-Type": "application/json"
},
"username": "username",
"password": "password",
"body": {
"target": {
"ref_type": "branch",
"type": "pipeline_ref_target",
"ref_name": "your_branch_name"
},
"variables": [
{
"key": "PACT_URL",
"value": "${pactbroker.pactUrl}"
}
]
}
}
}

Run a specific custom pipeline, for the changed pact:

{
"events": [{
"name": "contract_content_changed"
}],
"request": {
"method": "POST",
"url": "https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pipelines/",
"headers": {
"Content-Type": "application/json"
},
"username": "username",
"password": "password",
"body": {
"target": {
"ref_type": "branch",
"type": "pipeline_ref_target",
"ref_name": "your_branch_name",
"selector": {
"type": "custom",
"pattern": "pact-verification"
}
},
"variables": [
{
"key": "PACT_URL",
"value": "${pactbroker.pactUrl}"
}
]
}
}
}

Ref:

Buildkite - trigger build

{
"events": [
{
"name": "contract_content_changed"
}
],
"request": {
"body": {
"branch": "master",
"commit": "HEAD",
"message": "Build all the things! :rocket:",
"env": {
"PACT_URL": "${pactbroker.pactUrl}"
}
},
"headers": {
"Authorization": "Bearer TOKEN",
"Content-Type": "application/json"
},
"method": "POST",
"url": "https://api.buildkite.com/v2/organizations/<ORG>/pipelines/<PIPELINE>/builds"
}
}

Ref:

GitLab - trigger build

{
"request": {
"method": "POST",
"url": "https://gitlab.com/api/v4/projects/:id/ref/:ref/trigger/pipeline?token=:token&variables[PACT_URL]=${pactbroker.pactUrl}",
"headers": {
"Accept": "application/json"
}
},
"events": [
{
"name": "contract_content_changed"
}
]
}

Ref:

TeamCity - Trigger Build

{
"description": "Trigger 'contract_content_changed' event",
"provider": {
"name": "<Provider name>"
},
"events": [
{
"name": "contract_content_changed"
}
],
"request": {
"method": "POST",
"url": "https://<TEAMCITY_URL>/app/rest/buildQueue",
"headers": {
"Accept": "application/json",
"Content-Type": "application/json",
"Authorization": "Bearer Token"
},
"body": {
"buildType": {
"id": "<Build Configuration Id>"
},
"branchName": "${pactbroker.consumerVersionBranch}",
"properties": {
"property": [
{
"name": "env.pactConsumerVersionBranch",
"value": "${pactbroker.consumerVersionBranch}"
},
{
"name": "env.pactConsumerName",
"value": "${pactbroker.consumerName}"
}
]
}
},
}
}

The webhook body accepts the body parameters available at the addBuildToQueue endpoint.

pactbroker.consumerVersionBranch will be available as an environment variable in the teamcity build under the name env.pactConsumerVersionBranch

Ref:

Jenkins - Trigger Build

The following example shows how to trigger a Jenkins build with parameters.

{
"description": "Trigger ${pactbroker.provider} build on Jenkins",
"provider": {
"name": "<PROVIDER>"
},
"consumer": {
"name": "<CONSUMER>"
},
"events": [{
"name": "contract_content_changed"
}],
"request": {
"method": "POST",
"url": "https://<JENKINS_HOST>/job/listeners-acceptance/job/graphql/job/<JOB_NAME>/buildWithParameters?os_authType=basic",
"username": "<USERNAME>",
"password": "<TOKEN>",
"headers": {
"Accept": "application/json"
}
}
}

Ref:

Drone CI - Trigger Build

The following example shows how to trigger a Drone CI build with parameters.

{
"description": "Trigger ${pactbroker.provider} build on Drone CI",
"provider": {
"name": "<PROVIDER>"
},
"consumer": {
"name": "<CONSUMER>"
},
"events": [
{
"name": "contract_requiring_verification_published"
}
],
"request": {
"method": "POST",
"url": "https://<DRONE_HOST>/api/repos/<NAMESPACE>/<REPO_NAME>/builds?branch=${pactbroker.providerVersionBranch}&commit=${pactbroker.providerVersionNumber}&PACT_URL=${pactbroker.pactUrl}",
"headers": {
"Authorization": "Bearer <DRONE_TOKEN>"
}
}
}

PACT_URL will be available as an environment variable in your pipeline in steps that are triggered for event type custom.

Ref:

Triggering Notifications

Commit Status

Github - publish commit status

Report the pact verification status back to the consumer project in Github.

CLI
pact-broker create-webhook \
'https://api.github.com/repos/<organization>/<project>/statuses/${pactbroker.consumerVersionNumber}' \
-X POST \
-H "Content-Type: application/json" \
-d '{ "state": "${pactbroker.githubVerificationStatus}", "description": "Pact Verification Tests ${pactbroker.providerVersionTags}", "context": "${pactbroker.providerName}", "target_url": "${pactbroker.verificationResultUrl}" }' \
--user username:password \
--description "Publish pact verification status to Github" \
--contract-published \
--provider-verification-published \
--broker-base-url <your-broker>
JSON
{
"consumer": {
"name": "<consumer name>"
},
"events": [
{
"name": "contract_published"
},
{
"name": "provider_verification_published"
}
],
"request": {
"method": "POST",
"url": "https://api.github.com/repos/<organization>/<project>/statuses/${pactbroker.consumerVersionNumber}",
"headers": {
"Content-Type": "application/json"
},
"body": {
"state": "${pactbroker.githubVerificationStatus}",
"description": "Pact Verification Tests ${pactbroker.providerVersionTags}",
"context": "${pactbroker.providerName}",
"target_url": "${pactbroker.verificationResultUrl}"
},
"username": "USERNAME",
"password": "PASSWORD"
}
}

Collaboration Platforms

Slack - post notification - contract_published

{
"events": [
{
"name": "contract_published"
}
],
"request": {
"method": "POST",
"url": "https://hooks.slack.com/services/<webhook id>",
"headers": {
"Content-Type": "application/json"
},
"body": {
"channel": "#<your-channel-here>",
"username": "webhookbot",
"text": "New version of pact created for ${pactbroker.consumerName}/${pactbroker.providerName}: <${pactbroker.pactUrl}|contract-details>",
"icon_emoji": ":ghost:"
}
}
}

Slack - post notification - provider_verification_published

{
"events": [
{
"name": "provider_verification_published"
}
],
"request": {
"method": "POST",
"url": "https://hooks.slack.com/services/<webhook id>",
"headers": {
"Content-Type": "application/json"
},
"body": {
"channel": "#<your-channel-here>",
"username": "webhookbot",
"text": "Pact Verification published for $${pactbroker.consumerName}/$${pactbroker.providerName}<$${pactbroker.verificationResultUrl}|$${pactbroker.githubVerificationStatus}>",
"icon_emoji": ":ghost:"
}
}
}