Webhooks template library

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

Triggering Builds

Using the contract_requiring_verification_published event (recommended)

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 ${user.GithubToken}"
    },
    "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:

• Github repository_dispatch docs

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 ${user.GithubToken}"
    },
    "body": {
      "event_type": "pact_changed",
      "client_payload": {
        "pact_url": "${pactbroker.pactUrl}"
      }
    }
  }
}

Ref:

• Github repository_dispatch docs

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:

• Travis triggering builds docs

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:

• Bamboo Queue documentation

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:

• Azure DevOps Builds API page

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:

• Bitbucket API page
• Bitbucket App Password

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:

• Buildkite API

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:

• GitLab - Adding a new trigger
• GitLab - Pipeline triggers

TeamCity - trigger build

If you use TeamCity and know out how to pass parameters into the build, can you please submit a PR to update this example.

{
  "events": [
    {
      "name": "contract_content_changed"
    }
  ],
  "request": {
    "method": "POST",
    "url": "https://teamcity.net/app/rest/buildQueue?",
    "headers": {
      "Content-Type": "application/xml",
      "Authorization": "bearer token"
    },
    "body": "<build><buildType id='YourJobId'\/><\/build>",
    "username": "username",
    "password": "password"
  }
}

Ref:

• TeamCity - REST Authentication
• TeamCity - Triggering Build

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:

• Jenkins Remote API.

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:

• Drone API - Build Create.

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:"
    }
  }
}