Bitbucket Data Center Trigger

Handle Bitbucket Data Center webhooks

Overview

This node acts as a webhook trigger for Bitbucket Data Center events. It listens to various repository and pull request events from a specified project and repository within Bitbucket Data Center, such as pushes, pull request creations, merges, comments, branch/tag changes, and mirror synchronizations. When one of the selected events occurs, the node captures the event payload and triggers the connected workflow.

Common scenarios include:

Automating CI/CD pipelines when code is pushed or pull requests are merged.
Notifying teams about repository changes or pull request activities.
Synchronizing external systems with repository events.
Auditing repository activity by capturing detailed event data.

Example: Trigger a workflow whenever a pull request is opened or updated to automatically run code quality checks or notify reviewers.

Properties

Name	Meaning
Authentication	Method used to authenticate API requests. Options: "Personal Access Token" or "Basic Auth".
Project	The Bitbucket Data Center project key containing the repository to monitor. This is a required field and options are dynamically loaded from the Bitbucket server.
Repository	The repository slug within the selected project to monitor for webhook events. Required and dynamically loaded based on the chosen project.
Events	One or more Bitbucket Data Center webhook event types to listen for. Multiple selections allowed. Examples include repository pushes, pull request opened/merged/declined, branch/tag creation/deletion, comment added/edited, and mirror synchronization events.

Output

The node outputs JSON data representing the webhook event received from Bitbucket Data Center. The structure varies depending on the event type but generally includes:

event: The event key string identifying the type of event (e.g., repo:refs_changed, pr:opened).
headers: HTTP headers from the webhook request.
body: The full webhook payload.
Additional top-level properties extracted for convenience, depending on event type:
- For repository events (repo:*): may include repository, actor, and changes.
- For pull request events (pr:*): may include pullRequest, repository, actor, comment, and previous state fields like previousTitle.

No binary data output is produced by this node.

Dependencies

Requires access to a Bitbucket Data Center instance.
Needs an API authentication credential configured in n8n, either via a personal access token or basic authentication.
The node dynamically loads projects and repositories from the Bitbucket server using authenticated API calls.
The Bitbucket Data Center server URL must be configured in the credentials.

Troubleshooting

Webhook not triggering: Ensure the webhook is properly created on the Bitbucket server for the selected project/repository and events. Check that the node’s webhook URL is accessible by Bitbucket.
Invalid event key error: If the incoming webhook does not contain a valid x-event-key header or it is not among the selected events, the node will ignore the request.
Authentication errors: Verify that the API credentials are correct and have sufficient permissions to create webhooks and read project/repository information.
Request origin validation failure: The node expects the user-agent header to include "Atlassian" to confirm the request is from Bitbucket Data Center; otherwise, it throws an error.
API request failures: Errors during loading projects or repositories or webhook management indicate connectivity or permission issues with the Bitbucket server.