Troubleshoot webhooks

Still need help?

The Atlassian Community is here for you.

Ask the community

When you perform an action to trigger a webhook and it doesn't work, you can use the Request log and Request detail pages to figure out what went wrong. Note that you may need to know the Bitbucket Cloud IP addresses to add to the allowlist.

Webhook payload is limited to 256 KB. Webhooks may silently fail to trigger if their payload is too large.

Request Logs

If you aren't sure if a webhook triggered properly, you can look at the details of the request. In order to do that, you will need to enable the history of your webhooks. You can follow the next steps to accomplish that: 

  • Open your Repository > Repository settings > Webhooks > View requests 
  • Select the Enable history option: 

After enabling the history, Bitbucket will start recording every new webhook log. 

If necessary, select the Load new requests button to refresh the page and display any further requests.

list of request logs for the webhook

  1. Events: Lists the events that triggered the webhook.

  2. Request time: Indicates when the event occurred.

  3. View details: Select to see the details of event requests.

  4. Status: Displays the outcome of the request.

When Bitbucket sends a request, the log indicates the outcome of the request with one of these:

  • An HTTP status code

  • TIMEOUT, if the request timed out before connecting

  • NETWORK ERROR, if the request couldn't connect

If the status code in the payload response is in the 500-599 range, Bitbucket automatically resends the request up to two more times. If an event had multiple attempts, the request log includes the details for each attempt.

If Bitbucket doesn’t receive the response to a request after 10 seconds, the request will timeout. To avoid timeouts, you can acknowledge receipt of the request by replying with an appropriate response before doing any expensive processing on your end.

If you want to know the number of attempts made for an event request, select View details and look for the Request attempts number, which includes the number of automatic attempts. This number is also available in the X-Attempt-Number HTTP header of each request.

Request Details

When you select the View details link next to a logged event, you see details of the logged request event, the event payload, and header that Bitbucket sends to your server, and the response and header your server sends back to Bitbucket.

If any failures occur while sending webhooks, this view will display the attempts that were made to deliver them. For each attempt, it shows the request and response details (including response status and headers). In the response status, the client timeout will be reported as -1.

For explanations of what you may see under the Request Headers and Request Body tabs, see the event payloads. If an error prevents your server from sending a response back to Bitbucket, the Response Headers and Response Body tabs won't appear. 

Webhook URL

To ensure that we deliver webhooks successfully, it is best to either provide a URL that is already appropriately encoded, or a URL that does not have encoding for any of its components, in which case, we will encode it. The URL itself must be in the correct format i.e. It should not contain spaces, special characters like <>^ etc.

If you have a URL with the username/password component and the username contains the @ sign, you will need to encode it. For example, configure your URL to be:

instead of:

There are several API mocking sites available that you can use to test, inspect payload and create mock. Here are a few options you can consider:

  • Mockaroo: Mockaroo is a powerful tool for creating realistic test data for APIs. It allows you to create custom data sets and generate mock API responses based on your specifications.

  • Postman: Postman is a popular API development platform that also offers API mocking capabilities. You can easily create mock endpoints based on your API specifications and test your application without the need for a real backend.

  • Beeceptor: Beeceptor is a cloud-based service that allows you to create mock APIs and test your application's API interactions without the need for a real backend.
Last modified on Dec 18, 2023

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.