Troubleshoot webhooks

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. From the list of webhooks, click the View requests link to open a log page with a recent history of requests for that webhook and what each request returned. If necessary, click the Load new requests button to refresh the page and display any new 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: Click to see the details of event requests.

  4. Status: Displays the outcome of the request.

When Bitbucket sends a request, the log indicates 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, click 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 click 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.

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 do not 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.

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 https://someone%40somewhere.com:password@host.com/webhooks instead of https://someone@somewhere.com:password@host.com/webhooks.

Last modified on Feb 18, 2021
Cached at 7:00 PM on Oct 27, 2021 |

Additional Help