Verify webhook signature with example Python code in Bitbucket Cloud
Platform Notice: Cloud Only - This article only applies to Atlassian products on the cloud platform.
Summary
This article covers how to validate Bitbucket Cloud webhook deliveries using Python code to match signatures with secret keys.
Webhook security validation
The webhook "secret" feature in Bitbucket Cloud enhances security by allowing you to validate the authenticity of webhook deliveries, ensuring they originate from Bitbucket Cloud. We have included "Hello World" examples in the webhook documentation, but slight modifications are required to test it with real-world payload examples.
In the solution section below, we provide a sample Python code that calculates and matches the signature using the secret key, payload value, and the "x-hub-signature" obtained from the headers section in the "View Requests" tab.
Solution
Trigger webhook
You need to have admin access to the repo to perform these steps.
Open the repository on Bitbucket Cloud's website.
Select Repository Settings from the left sidebar.
Select Webhooks from the new left sidebar, under the Workflow section.
Locate the specific webhook whose signature you want to verify, and select View requests under the column Actions for this webhook.
By default, history is turned off for webhooks. If you see the button Enable history, select it.
To see new requests on this page, you will then need to perform an action that triggers the webhook.
After performing an action that triggers the webhook, select the button Load new requests to see the event.
Select View details for this new event.
In the View Details section, you can observe the response, request headers, and body.
Capture the X-Hub-Signature from the request headers section (you will need it later).
You also need to know the webhook's secret.
Copy the payload under the body section and paste it into a new file named, for example, json_payload.json.
The below Python script performs the following tasks:
Reads the content of the "json_payload.json", strips leading and trailing whitespaces, removes spaces after colons, and puts it in a single line.
Calculates an HMAC (Hash-based Message Authentication Code) using the SHA-256 hash function. The HMAC is computed using a secret key and the payload obtained from the JSON file.
Compares the calculated HMAC signature with a given signature (captured from the request headers section). It uses the hmac.compare_digest function for a secure comparison of the two signatures.
This script prints whether the signatures match or not, along with the expected and actual signatures. It ensures a reliable verification process for webhook signatures.
Perform these steps:
Create a new file, named e.g., verify_sig.py, in the same directory as the file json_payload.json you created in Step 3 of View Details above.
Copy and paste the script below into the file verify_sig.py.
In line 19 of the script, replace the value of the variable given_signature with the value of the X-Hub-Signature you captured in Step 1 of View Details above.
In line 22 of the script, replace the value of the variable secret with the value of the webhook's secret.
Save your changes.
Run the script with the command:
python3 verify_sig.py.
Script verify_sig.py
import hashlib
import hmac
import json
# Read the JSON payload from the file
with open("json_payload.json", "r") as file:
# Load JSON data from the file
payload_data = json.load(file)
# Convert the payload data back to a single-line JSON string
modified_payload = json.dumps(payload_data, separators=(',', ':'), ensure_ascii=False)
# Print the original and modified payloads
print("Original Payload:")
print(json.dumps(payload_data, indent=2)) # Pretty print the original payload
print("\nModified Payload:")
print(modified_payload) # Print the modified payload
# Given HMAC signature
given_signature = "sha256=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
# Extract the secret key
secret = ""
# Calculate the signature
hash_object = hmac.new(
secret.encode("utf-8"),
msg=modified_payload.encode("utf-8"),
digestmod=hashlib.sha256,
)
calculated_signature = "sha256=" + hash_object.hexdigest()
# Compare the signatures
if given_signature is not None and not hmac.compare_digest(calculated_signature, given_signature):
print(
"Signatures do not match\n"
f"Expected signature: {calculated_signature}\n"
f"Actual signature: {given_signature}"
)
else:
print("Signatures match")
print(f"Expected signature: {calculated_signature}")
print(f"Actual signature: {given_signature}")Detailed script explanation:
The script reads a JSON payload from the file named "json_payload.json".
It loads the JSON data into a Python dictionary called
payload_data.The script then converts the
payload_datadictionary back into a single-line JSON string calledmodified_payload.It prints the original payload (
payload_data) in a pretty-printed format and the modified payload (modified_payload) as a single line.The script calculates an HMAC signature using the modified payload and a secret key.
It compares the calculated signature with a given signature (
given_signature).If the signatures match, it prints a message confirming the match; otherwise, it prints the expected and actual signatures to indicate a mismatch.
Was this helpful?