Setting up a repository hook with JSON

To use the notification hook in Notifyr a JSON configuration must be added to the root of your source code. The advantage of having a JSON file that is part of your source code is that:

  • You can include a default setting in your project architecture.
  • Developers can include their own notification if required
  • Much more flexibility on the type of notifications based on branches

Prepare your repository for the notification hook

For a repository to use the notification hook, a JSON file named notifications.json needs to be added to the root of the repository. A bare minimum notifications.json file would look like this:

minimum notifications.json
	"rules": [{
		"notifications": [{
			"address" : "[email protected]"

The above configuration would send a notification to [email protected] for every push made to the repository. 

The JSON configuration has more options and flexibility in when to send what kind of notification and to who. Take the following configuration for example:

  "rules": [
        "match": "/**/feature/*",
		"inverted" : false,
        "notifications" : [
                "address" : "[email protected]",
                "sendSeparate" : true,
                "includeDiff" : true
                "address" : "[email protected]",
		        "prefix" : "[HOOK]"
        "match": "/**/*",
		"events": ["Push", "BranchCreate"],
        "notifications": [
            { "address": "[email protected]" }

There are a few things happening here, but the first thing you might notice is that you are able to specify multiple rules. Let's explain the options

matchAn Ant-based pattern to match your branch against
/**/* matches all branches (default)
/**/feature/* matches all feature branches

SINCE 4.3.0

An Ant-based pattern to match your file paths against
/**/* matches all paths (default)
/**/*.xml matches all XML files in your commit

invertedtrue or false should the result from the match be inverted? Defaults to false

SINCE 4.1.0

An array of events on which the rule should be triggered. Possible events are

PushTriggered when code is pushed to a repository, also triggered when editing a file in Bitbucket.
BranchCreateTriggered when a new branch is created
TagCreateTriggered when a new Tag is created
PullRequestCreateTriggered when a new Pull Request is created
PullRequestMergeTriggered when a Pull Request is merged
PullRequestDeclinedSINCE 6.1.0
PullRequestReopenedSINCE 6.1.0
PullRequestDeletedSINCE 6.1.0
PullRequestCommentedSINCE 6.1.0
PullRequestParticipantStatusSINCE 6.1.0
AllTrigger for all the implemented events – default

an array of notifications:

addressThe email address to send the notification to
prefixThe email subject prefix. Uses the system default if not specified
sendSeparateSet to true if you want to receive separate emails per commit
includeDiffSet to true if you want to include a file diff
onBranchCreatedSet to false when you don't want to receive a notification on newly created branches. Default to true
includeChangedFilesInclude a TOC with all changed files in the notification, defaults to false SINCE 5.2.0

Enable to Notification Hook

Repository administrators can set up the hooks that are available in Bitbucket by going to Settings > Hooks for a Bitbucket repository. Once installed, hooks are available across all repositories in a Bitbucket instance but are enabled separately on each repository in a project. 

To set up the Notification Hook:

  • Browse to the Hooks overview in your repository settings
    • Browse to the relevant repository
    • Choose Settings from the repository navigation
    • Select Hooks from the left menu
  • Toggle the Notifyr - Notification Hook setting to Enabled.