What are webhooks? – Bitly Support

Webhooks are a method of sending information from Bitly to an application outside of Bitly. In other words, they're a way to automate actions or updates between two different systems.

When an external application receives the Bitly data, it might send a notification, update records, or trigger actions every time someone clicks on a short link. Currently, webhooks only support click (aka decode) events.

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, read 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! Any app that accepts webhook responses will have different actions that can occur when receiving one.

A company that sends Bitly short links to customers confirming a delivery status for a product 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.

An organization that wants to update a database to track click data 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, you'll need to post the query parameter as 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'll be 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, you'll need to 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.

Articles in this section