Tutorial: Create and Trigger a Webhook
Let's create a webhook and see if we can trigger it! We have created a repository with a simple Flask server (that receives Bitbucket webhooks) for you to play with.
Before you start, make sure you have the following requirements:
Step 1: Create the URL for your webhook
Now you can start to get the server ready before adding the webhook:
Start by cloning the following repository to set up the server on your local system: https://bitbucket.org/atlassianlabs/webhook-listener. From the Webhook Listener repository and copy the clone URL. From the directory where you keep your repositories, enter the clone command and URL into your terminal.
$ git clone email@example.com:atlassianlabs/webhook-listener.git
Change your directory to the
$ cd ~/<repos_directory>/webhook-listener
REQUIREMENTS.txtfile you just cloned.
$ pip install -r REQUIREMENTS.txt
.envfile from the
webhook-listenerrepository on your local system. The file contains one line:
NGROK_SUBDOMAIN=bbwebhook. Set the
NGROK_SUBDOMAINon this line to your preferred subdomain for the server. For the purposes of this tutorial, change it to your first name.
Start the ngrok tunnel and Flask server with the following command:
$ honcho start
Before you run this command or if
honcho startdoes not work, you may need to make sure that your ngrok directory is in a directory on your
Not long after you run the
honcho startcommand, you see the command line return the following:
You can access this webhook publicly via at http://<first_name>.ngrok.io/webhook You can access ngrok's web interface via http://localhost:4040
Take note of both these URL's. The first one is the webhook URL that you use to access the server. Use the second URL to see the requests you send the first URL.
Step 2: Create the webhook
- Now it's time to create a webhook for your own repository. From your repository in Bitbucket, click the Settings link on the left side, then click the Webhooks link.
- Click the Add webhook button to create a webhook for the repository.
- Enter Webhook Listener as the Title.
- Enter the URL to the server in the URL field, similar to
- Click Save. For the purposes of this tutorial, keep the Triggers as only a Repository Push.
- Now that you created a webhook, open your webhook's URL. You will see something like this:
Open the URL to ngrok's web interface:. You see the GET request that your browser makes to your server.
Step 3: Trigger the webhook
The next thing we want to do is push something to the repository to see if we can trigger the webhook. Start by creating a new file with the following text:
Let's try out a webhook.
- Save the file, as
file.txt, to your repository directory on your local system.
Add, commit, and push the file to your Bitbucket repository:
$ git add file.txt $ git commit -m 'Initial commit' $ git push
- Return to the ngrok URL and you will see the POST request with the event payload that Bitbucket sends to your server.
You have now successfully created and triggered a webhook!
Step 4: Update the Webhook Listener
- From the cloned repository on your local system, open the
Read through this file. Notice that it explains what prints to the command line after you run
honcho startand what prints to the webhook URL.
This file also includes code that uses data from the POST payload to output a notification.
@app.route('/webhook', methods=['GET', 'POST']) def tracking(): if request.method == 'POST': data = request.get_json() commit_author = data['actor']['username'] commit_hash = data['push']['changes']['new']['target']['hash'][:7] commit_url = data['push']['changes']['new']['target']['links']['html']['href'] if _platform == "darwin": from pync import Notifier Notifier.notify('%s committed %s\nClick to view in Bitbucket' % (commit_author, commit_hash), title='Webhook received!', open=commit_url) else: print 'Webhook received! %s committed %s' % (commit_author, commit_hash) return 'OK' else: return displayHTML(request)
- Modify the
tracking()function to update how the Webhook Listener uses the POST data. You can update the payload parameters it uses or what the function does with the data.
- Save the
honcho startagain and push another file to your repository with the webhook.
You should see the changes you made to the