How Post Webhooks for Bitbucket sends data outside?

This guide is for Post Webhooks for the Bitbucket Atlassian Marketplace application.

Outgoing API

Post Webhooks for Bitbucket sends data outside using API in a particular format. The API may differ slightly depending on the version you use (we do treat this API as a feature and do our best, including having integration tests, to maintain backward compatibility).

The best is to run ngrok http 9999 in a terminal window, copy generated the HTTP URL, and use it in the Post Webhooks for Bitbucket configuration. Afterwards, open http://127.0.0.1:4040/inspect/http to inspect all data sent to ngrok url.

Common types

JAVA

interface BitbucketServerRepositoryOwner {
	String username;
	String displayName;
    String emailAddress;
}

interface BitbucketServerProject {
	String key;
	String name;
}

interface Link {
    String href;
    String name;
}

interface BitbucketServerRepository {
	String scmId;
	BitbucketServerProject project;
	String slug;
	Map<String,List<Link>> links;
    boolean public;
	String fullName; // repository full name
    BitbucketServerRepositoryOwner owner;
	String ownerName; // project name
}

interface BitbucketServerBranch {
	String displayId;
	String latestCommit;
}

interface BitbucketServerCommit {
	String message;
	String date;
	String hash;
	long authorTimestamp;
}

Pull request events

JAVA

interface BitbucketServerPullRequestEvent {
    private BitbucketServerRepositoryOwner actor;
    private BitbucketServerPullRequest pullrequest;
    private BitbucketServerRepository repository;
    private String comment;
}

interface BitbucketServerPullRequest {
	String id;
	String title;
	String link;
	String authorLogin;
	BitbucketServerPullRequestSource fromRef;
	BitbucketServerPullRequestSource toRef;
}

interface BitbucketServerPullRequestSource {
	String latestCommit;
	String displayId;
	BitbucketServerRepository repository;
    BitbucketServerBranch branch;
	BitbucketServerCommit commit;
}

Push event

CODE

interface BitbucketPushEvent {
    BitbucketServerRepositoryOwner actor;
    BitbucketServerRepository repository;
    BitbucketPushDetail push;
    String[] branches;
}

interface BitbucketPushDetail {
    BitbucketPushChange[] changes;
}

interface BitbucketPushChange {
    State new;
    State old;
    boolean created;
    boolean closed;
}

interface State {
    String type;
    String name;
    Target target;
}

interface Target {
    String type = "commit";
    String hash;
    String commitMessage;
}

Build status update events

JAVA

interface class BuildStatusEvent {
    String commit;
    String status;
    String url;
    BitbucketServerRepository repository;
}

HTTP header values

Here is our event type to header value map.

JAVA

.put(PULL_REQUEST_OPENED, "pullrequest:created")
.put(PULL_REQUEST_UPDATED, "pullrequest:updated")
.put(PULL_REQUEST_RESCOPED, "pullrequest:updated")
.put(PULL_REQUEST_REOPENED, "pullrequest:updated")
.put(PULL_REQUEST_MERGED, "pullrequest:fulfilled")
.put(PULL_REQUEST_DECLINED, "pullrequest:rejected")
.put(PULL_REQUEST_COMMENT, "pullrequest:comment")
.put(PULL_REQUEST_DELETED, "pullrequest:deleted")
.put(PULL_REQUEST_CANCELABLE_COMMENT, "pullrequest:comment")
.put(PULL_REQUEST_COMMENT_ACTIVITY, "pullrequest:comment")
.put(BUILD_STATUS_SET, "build:status")
.put(TAG_CREATED, "repo:push")
.put(BRANCH_CREATED, "repo:push")
.put(BRANCH_DELETED, "repo:push")
.put(REPOSITORY_MIRROR_SYNCHRONIZED, "repo:push")
.put(ABSTRACT_REPOSITORY_REFS_CHANGED, "repo:push")

Examples

Repository push

JSON

Header: 
X-Event-Key	repo:push

Body:
{
    "actor": {
        "username": "admin",
        "displayName": "Administrator",
        "emailAddress": "admin@example.com"
    },
    "repository": {
        "scmId": "git",
        "project": {
            "key": "PROJECT_1",
            "name": "Project 1"
        },
        "slug": "rep_1",
        "links": {
            "self": [
                {
                    "href": "http://localhost:7990/bitbucket/projects/PROJECT_1/repos/rep_1/browse"
                }
            ]
        },
        "public": false,
        "ownerName": "PROJECT_1",
        "fullName": "PROJECT_1/rep_1",
        "owner": {
            "username": "PROJECT_1",
            "displayName": "PROJECT_1",
            "emailAddress": null
        }
    },
    "push": {
        "changes": [
            {
                "created": false,
                "closed": false,
                "old": {
                    "type": "branch",
                    "name": "admin/add_filetxt-1591697551701",
                    "target": {
                        "type": "commit",
                        "hash": "0a943a29376f2336b78312d99e65da17048951db",
                        "commitMessage": "test commit message"
                    }
                },
                "new": {
                    "type": "branch",
                    "name": "admin/add_filetxt-1591697551701",
                    "target": {
                        "type": "commit",
                        "hash": "be2049fc0a90f6ee1d556fa236fec7de0fb1a577",
                        "commitMessage": "test commit message"
                    }
                }
            }
        ]
    }
}

Pull request approver

When the pull request is approved the event contains the approver.

CODE

"approver": {
    "username": "user",
    "displayName": "User",
    "emailAddress": "user@example.com"
}

How to create a new webhook?

Global Configurations for Bitbucket admins

Project Level Configurations

Repository Level Configurations

Updated: 15 Dec 2023