Create a Webhook

Use webhooks to be notified when a link is clicked.

Bitly's webhook endpoints can be configured in the web application or programmatically using webhook endpoints.

Configuring webhooks from the web app provides a user interface for configuring webhook endpoints.

Authentication

Bitly supports API Key & HTTP Basic Auth for posting the webhook. 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

Bitly also supports using OAuth 1.0 when creating or updating your webhooks via the API or web app. To utilize this feature with the API, you will need to add the following fields to your request body. Our documentation has additional information for the OAuth request body schema.

oauth_url: www.youroauthurl.com
client_id: yourclientid
client_secret: yourclientsecret

On all subsequent webhook events, we will then attempt to call your OAuth service to retrieve a token, which will be appended as a header on all responses in the form of Authorization: Bearer {token}. Please note that we expect your OAuth service to follow standard OAuth 1.0 conventions. Currently we are only supporting grant_type of client_credentials. We will assume a token is expired if we receive a 401 response when sending the webhook payload, and we will attempt to retrieve a new token.

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 unique identifies a single click
• Date and time of click
• Long URL
• Parameters passed through from long URL (if available with your subscription)
• bitlinkID (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
• (Optional) Tags associated with the link

To include tags in the payload, add the following field to your request body when creating or updating a webhook:

fetch_tags: true

Enabling tags may result in delays to the payload delivery as we gather the data internally. The tags feature is only available when utilizing our API, and is not yet available in our web application.

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",
    "tags": [
        "tagA",
        "tagB"
    ],
    "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 set webhooks to alert status should we receive an unsuccessful HTTP status code response. Each webhook event will make five total attempts to send a payload to your designated URL endpoint. After the fifth attempt, the event payload will not be requeued and will not be re-sent. After the first failure, an email will be sent to all of your account administrators notifying you that there's a problem.

Subsequent webhook events after the first failed event will be allowed to fail for 24 hours before the webhook is deactivated. Should a webhook event return a successful response, the webhook will be automatically removed from alert status, and no email will be sent. Once deactivated a final email will be sent. Once a webhook is deactivated, it will need to be reactivated manually through the web app or through the update webhook API endpoint.