Sign in or subscribe for support Sign in

Articles in this section

How do I troubleshoot webhooks?

Alexander Hancock
  • Updated

We make multiple attempts to send a webhook event if the initial delivery fails. After the first failed attempt, we send an email to all of your account admins alerting you to the issue. We make five attempts before removing the event from the queue.

If additional webhook events fail, we deactivate the webhook and send another email to your account admins.

To learn more about how we address webhook errors, go to the webhooks page in our developer documentation and scroll down to Webhook Errors.

What causes webhook errors?

A webhook error could be caused by an issue with your app or server — or it could be because the webhook is not configured correctly in Bitly. An admin on your Bitly account can confirm the webhook configuration is correct.

To check your webhook configuration:

This process uses your account settings to check your webhook configuration. You can also do this via the Bitly API.

  1. Log in to your Bitly account.
  2. Click Settings in the left sidebar.
    Bitly-settings-global.png
  3. Under Account settings, click Webhooks.
    Bitly_Webhooks_-_settings_menu.png
  4. Click the three dots next to the webhook you're troubleshooting and select Edit.
    Bitly_Webhook_-_edit_menu.png
  5. Confirm that the Endpoint URL is correct.
    Bitly_Webhook_-_edit_screen.png
  6. If your webhook requires OAuth compliance, verify that your OAuth providers settings are correct as well.
    Bitly_Webhook_-_OAuth_info.png

If you've confirmed your configuration in Bitly and checked for issues with your app and server, submit a request to our support team so that we can help identify and fix the issue.

Verify your Webhook through the API

If you have access to and know how to use the Bitly API, test your webhook with our API test tool. The verify webhook endpoint sends a test webhook event message to your webhook's endpoint URL. This helps you test your webhook without requiring a click or QR Code scan.

The easiest way to test is through your terminal/command prompt of choice, with the curl command line tool. You can also use apps like Postman, along with our Postman Bilty API Collection. These instructions use curl to verify the webhook.

  1. Generate an access token.
  2. If you don't already have your Organization's Globally Unique Identifier (GUID) and webhook GUID, first collect this information. If you have both, skip to step 3.
    1. To find your OrgGUID, check your browser windows URL while in the webhook settings menu in your Bitly account. In this example, the OrgGUID is :org_guid.
      Bitly_Webhooks_-_OrgGUID.png
    2. To find your webhook GUID, request your webhook details through the API with a Get Webhooks request. In the curl request below, replace {TOKEN} with your access token from step 1, and :org_guid with your GUID from step 2a. Find the webhook GUID in the curl response. 
      curl \
      -H 'Authorization: Bearer {TOKEN}' \
      -X GET \
      https://api-ssl.bitly.com/v4/organizations/:org_guid/webhooks
  3. Send the curl request to Verify Webhook. In the curl request below, replace {TOKEN} with your access token from step 1, and :webhook_guid with the GUID found in step 2b. 
    curl \
    -H 'Authorization: Bearer {TOKEN}' \
    -X POST \
    https://api-ssl.bitly.com/v4/webhooks/:webhook_guid/verify
  4. This test event should help troubleshoot any issues related to your endpoint.

If you've confirmed your configuration in Bitly and checked for issues with your app and server, submit a request to our support team so that we can help identify and fix the issue.