How Post Webhooks for Bitbucket sends data outside?

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: 13 Jun 2023