Create and trigger a webhook tutorial

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:

• Python & Pip

• ngrok

Step 1: Create the URL for your webhook

Now you can start to get the server ready before adding the webhook:

1. 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.

   1 $ git clone git@bitbucket.org:atlassianlabs/webhook-listener.git

2. Change your directory to the webhook-listener directory.

   1 $ cd ~/<repos_directory>/webhook-listener

3. Install the REQUIREMENTS.txt file you just cloned.

   1 $ pip install -r REQUIREMENTS.txt

4. Open the .env file from the webhook-listener repository on your local system. The file contains one line: NGROK_SUBDOMAIN=bbwebhook. Set the NGROK_SUBDOMAIN on this line to your preferred subdomain for the server. For the purposes of this tutorial, change it to your first name.

   1 NGROK_SUBDOMAIN=<first_name>

5. Start the ngrok tunnel and Flask server with the following command:

   1 $ honcho start

   Before you run this command or if honcho start does not work, you may need to make sure that your ngrok directory is in a directory on your PATH.

   Not long after you run the honcho start command, you see the command line return the following:

   1 2 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

1. Now it's time to create a webhook for your own repository. From your repository in Bitbucket, select Repository settings on the left sidebar, then select Webhooks.

2. Click the Add webhook button to create a webhook for the repository.

3. Enter Webhook Listener as the Title.

4. Enter the URL to the server in the URL field, similar to http://<first_name>.ngrok.io/webhook.

5. Click Save. For the purposes of this tutorial, keep the Triggers as only a Repository Push.

6. Now that you created a webhook, open your webhook's URL.

7. Open the URL to ngrok's web interface: http://localhost:4040/. You see the GET request that your browser makes to your server.
   
   

Step 3: Trigger the webhook

1. 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:

   1 Let's try out a webhook.

2. Save the file, as file.txt, to your repository directory on your local system.

3. Add, commit, and push the file to your Bitbucket repository:

   1 2 3 $ git add file.txt $ git commit -m 'Initial commit' $ git push

4. 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

1. From the cloned repository on your local system, open the listener.py file.

2. Read through this file. Notice that it explains what prints to the command line after you run honcho start and what prints to the webhook URL.
   This file also includes code that uses data from the POST payload to output a notification.

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 @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'][0]['new']['target']['hash'][:7] commit_url = data['push']['changes'][0]['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)

3. 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.

4. Save the listener.py file.

5. Run honcho start again and push another file to your repository with the webhook.

You should see the changes you made to the listener.py file.