Webhooks

Webhooks allow you to trigger an HTTP request when an event happens in API Hub for Contract Testing. For example, when 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 update PR status checks when a verification is published.

In this screen, you can create and manage these webhooks.

See more about webhooks.

Listing all Webhooks

Here you can create, edit and view your webhooks. You can use the filter controls on the table to find a specific webhook.

Creating a Webhook

Field	Description
Team	When creating or editing a webhook, users with the `webhook:manage:team` permission (by default, assigned to the `User` role) must assign a webhook to a team. Users with the `webhook:manage:*` ermission (by default, assigned to the `Administrator` role) may choose not to assign a webhook to any team. Team selection affects which secrets are available for use in the webhook. See the Secrets section below.
Description	A description of your webhook
Consumer	You can select a specific consumer for the webhook, or `ALL` for all consuers.
Provider	You can select a specific provider for the webhook, or `ALL` for all providers.
Events	Select the events for which you want the webhook to fire (Mandatory to select one).
Method	All webhook requests will be HTTP Post.
URL	The URL to send the webhook request to (Mandatory). You can use dynamic variables in this field.
Headers	Headers as `KEY: VALUE` pairs to set on the request.
Body	The request body. You can use dynamic variables in the body.
Basic auth username	The username to use if your webhook requires Basic HTTP authentication
Basic auth password	The password to use if your webhook requires Basic HTTP authentication
Enabled	Uncheck this if you wish to disable the webhook

Webhook event types

Contract published that requires verification

This webhook is used to trigger one or more build that run the provider verification for a newly published pact. This event fires once for each of the following provider versions that are missing a verification result for the pact just published:

The latest version from the provider's main branch
Any version currently deployed to an environment

The provider versions are de-duplicated by version number, so that if the same provider version is the head, and/or deployed to multiple environments, the webhook will only trigger once for each provider version. The template parameter ${pactbroker.providerVersionDescriptions} will describe which branch/stage that particular provider version number pertains to, for example, "latest from main branch, deployed in test"

See the Pact Broker docs for more information on the usage of this event.

Contract published with changed content or tags

If your pact is published without any tags applied to the consumer version, this event will be fired if the pact content is different from the previous version.
If your pact is published with tags applied to the consumer version, you can think of all the pacts that share the same tag name as forming a time ordered "pseudo branch". This event will fire if the new pact for any of the "pseudo branches" is different from the previous version. One of the implications of this is that if a pact is published with the same content as a previous version, but with a new tag, this event will fire as it is considered to be the first version of a new pseudo branch.
If you want a provider build to be triggered by pact changes, select this event for your webhook.

Contract published

This event fires every time a pact is published.

Provider verification published

This event fires every time a provider verification is published.

Dynamic Variables

Secrets

User-defined secrets that have the same team assigned as the webhook may be used in the path of the URL, the headers, body, username and password. They will be replaced with their appropriate values at runtime. For webhooks that have no team assigned, only secrets that also have no team assigned may be used. The list of secrets available for use in a particular webhook are shown in the Dynamic variables section (click on the heading to display the values).

To use a secret in a webhook, use the expression ${user.<SECRET_NAME>} for example ${user.ciToken}.

API Hub for Contract Testing

The following variables may be used in the path and query parameters of the URL, the headers, body, username and password. They will be replaced with their appropriate values at runtime.

Expression	Description
`${pactbroker.consumerName}`	The consumer's name
`${pactbroker.providerName}`	The provider's name
`${pactbroker.consumerVersionNumber}`	The version number of the most recent consumer version associated with the pact content.
`${pactbroker.providerVersionNumber}`	The provider version number for the verification result
`${pactbroker.providerVersionTags}`	The list of tag names for the provider version associated with the verification result, separated by ", ".
`${pactbroker.providerVersionBranch}`	The repository branch associated with the provider version
`${pactbroker.consumerVersionTags}`	The list of tag names for the most recent consumer version associated with the pact content, separated by ", "
`${pactbroker.consumerVersionBranch}`	The repository branch associated with the consumer version
`${pactbroker.pactUrl}`	The "permalink" URL to the newly published pact (the URL specifying the consumer version URL, rather than the "/latest" format.
`${pactbroker.verificationResultUrl}`	The URL to the relevant verification result.
`${pactbroker.githubVerificationStatus}`	The verification status using the correct keywords for posting to the Github commit status API. See https://developer.github.com/v3/repos/statuses
`${pactbroker.bitbucketVerificationStatus}`	The verification status using the correct keywords for posting to the Bitbucket commit status API. See https://developer.atlassian.com/server/bitbucket/how-tos/updating-build-status-for-commits/
`${pactbroker.azureDevOpsVerificationStatus}`	The verification status using the correct keywords for posting to the Azure DevOps GitStatusState API. See https://docs.microsoft.com/en-us/rest/api/azure/devops/git/statuses/create?view=azure-devops-rest-6.0
`${pactbroker.consumerLabels}`	The list of labels for the consumer associated with the pact content, separated by ", ".
`${pactbroker.providerLabels}`	The list of labels for the provider associated with the pact content, separated by ", ".
`${pactbroker.providerVersionDescriptions}`	The descriptions of the provider version(s) for which the contract_requiring_verification_published webhook has been triggered. Only populated for the contract_requiring_verification_published event.
`${pactbroker.eventName}`	The name of the event that triggered the webhook

Basic auth

If your webhook requires basic auth, we recommend using a secret to store the password value. Reference the secret value in the password field by entering ${user.<SECRET_NAME>} where <SECRET_NAME> is the name of the secret. For example, ${user.myBasicAuthPassword}.

Important

For security reasons, if you enter a password value directly into the password field (without using a secret), the password value will not be displayed the next time the webhook is viewed. The existing password value will be maintained when other fields are updated. To update the password, enter a new value and click the Update button.
If you wish to test the execution of a webhook with a plain text (non-secret) password, you will need to enter it into the password field again before pressing the test button.

Viewing a Webhook

Editing a Webhook

Under the "General Settings" tab, you can modify an existing webhook. See "Creating a Webhook" above for more on the options in this form.

Viewing Webhook Executions

When a webhook is triggered by an event, the execution is logged. You can view these executions under the "Triggered Webhooks" tab:

Note

Webhooks automatically re-try up to 7 times, using an exponential backoff algorithm. The UI shows only the last retry. You can see how many attempts it took by hovering over the row.

Viewing the Logs

Clicking on any row in the table will expand the log entries. You can expand multiple rows at the same time to compare executions:

In this section: