Sign in or subscribe for support Sign in

Articles in this section

What are webhooks?

Tony Roma

Webhooks are a method of sending information from Bitly to an application outside of Bitly. They're a way to automate actions or updates between Bitly and another system.

For example, when someone clicks on one of your Bitly links, your webhook can send data about the click to another application. That application can then send a notification, update records, or trigger another action.

Currently, Bitly's webhooks only support click events.

Bitly___webhooks.png

To create a webhook, you'll need an endpoint URL to tell Bitly where to send the click data. The endpoint URL is like an address for your receiving application, usually found in the application's account settings.

If you'd like to jump right into setting one up, check out How to configure a webhook. Webhooks can only be set up by your Bitly account administrators.

What can you do with webhooks?

Quite a lot! Each app that accepts webhooks has different actions that can occur after receiving one.

Take, for example, a company that sends Bitly short links to customers confirming a delivery status for a product. They could set a webhook to send that confirmation click to a CRM. The CRM may have an automated process that then sends a Thank You email to the customer. That email might even prompt the customer to leave a review for the product.

How about an organization that wants to update a database to track click data? They could point a webhook directly to the database or, if that's not an option, use a service like Zapier to update fields. This can be a faster way of collecting and analyzing data than periodically pulling information through the Bitly API.

There are many more possibilities, depending on where you're sending the data.

Let's get technical

Working with webhooks does require some technical knowledge, so work with your technical staff or a developer if the following information doesn't make sense to you.

Authentication

Bitly supports API Key, HTTP Basic Auth, and OAuth 2.0 credentials for posting the webhook. Learn more about these authentication methods on our dev site.

For API Key and HTTP Basic Auth, the query parameter needs to be part of the callback URL.

Example API Key:

https://yourapp.domain/webhook?key=abc123

Example basic auth:

https://user:password@customer.domain/webhook

For OAuth 2.0, you're asked to enter these values when you configure your webhook:

oauth_url: youroauthurl.com/token
client_id: yourclientid
client_secret: yourclientsecret

To create or update webhooks with the API, add those fields to your POST or PATCH request body.

Response format

Bitly sends webhook responses, formatted in JSON, over HTTP as HTTPS POST requests. We'll send the payload to the URL that you enter into your account settings in Bitly.

The payload

A Bitly webhook payload will include the following information with each click event:

  • Event ID, which uniquely identifies a single click event
  • Date and time
  • Long URL
  • Parameters passed through from long URL (if available with your subscription)
  • Bitlink (short link and associated data)
  • Country where the link was clicked
  • Referrer
  • Device type
  • Account and Group ID related to this link
  • Webhook ID that an event is related to
  • Tags (if you select this option when you configure your webhook)

Here's an example:

{
    "event_id": "42f14eec-d1dc-11ea-8bbb-080027c1cea9",
    "datetime":"2019-12-20T07:54:54+0000",
    "url":"https://long.url.net/wiki/spaces/longer/data/665092146/",
    "bitlink":"write4plebs.com/pendorama",
    "passed_params":"",
    "country":"US",
    "referrer": "direct",0
    "device_type": "Desktop",
    "webhook_guid": "W0123456789",
    "organization_guid": "O1234567890",
    "group_guid": "B0123456789",
    "references": {
        "bitlink": "https://api-ssl.bitly.com/v4/bitlinks/write4plebs.com/pendorama",
        "group": "https://api-ssl.bitly.com/v4/groups/B0123456789",
        "organization": "https://api-ssl.bitly.com/v4/organizations/O1234567890",
        "webhook": "https://api-ssl.bitly.com/v4/webhooks/W0123456789"
    }
}

Webhook errors

Bitly will make multiple attempts to send a payload if the first attempt fails. After failing multiple times, the webhook will be automatically deactivated and an email will be sent to all your account administrators notifying you that there's a problem.