BitlyDeveloper
Start Now

Create a Webhook

Use webhooks to be notified when a link is clicked, Link-in-bio button is clicked or QR code is scanned.

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 currently supports API Key, HTTP Basic Auth, and OAuth 2.0 client credentials grant for posting webhook events.

API Key & HTTP Basic Auth

For API key or HTTP Basic Auth you'll need to append the query parameter as part of the callback URL during the webhook creation or update through either the API or the web app.

Example API Key:

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

Example basic auth:

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

OAuth 2.0 Client Credentials Grant

Bitly also supports using OAuth 2.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 POST or PATCH request body. Our documentation has additional information for the OAuth request body schema.

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

On all subsequent webhook events, we will then attempt to call your OAuth provider service to retrieve an access token. The authentication POST request will be sent to the designated OAuth URL with the following request format:

POST /token HTTP/1.1
Host: youroauthurl.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Where Authorization: is set to "Basic " + base64encode(client_id + ":" + client_secret).

Bitly will be expecting a HTTP response with 200 (OK) status code with the following format:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "expires_in":3600
}

Bitly will use the access_token appended as a header on the Webhook event POST request in the form of Authorization: Bearer {token}. Please note that we expect your OAuth service to follow standard OAuth 2.0: Client Credentials Grant conventions. Currently we are only supporting grant_type of client_credentials. We will assume a token is expired if we receive a 401 (Unauthorized) status code response when sending the webhook payload, and we will attempt to retrieve a new token.

Webhook Event Request Format

Bitly sends webhook events, as HTTPS POST requests, with the request body containing a JSON formatted webhook event payload. We'll send the payload to the webhook URL defined you enter into your account settings in Bitly.

The Webhook Event Payload

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

  • Event ID which unique identifies a single event
  • Event Type - "engagement" was previously "click" updated to be more accurate as it is inclusive of link clicks, QR code scans, and Link-in-bio button clicks
  • Date and time of event
  • Long URL that the user was redirected to
  • Parameters passed through from long URL (if available with your subscription)
  • Bitlink - the domain and backhalf that was interacted with
  • Country where the link was interacted with
  • 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
  • Time Zone where the link was interacted with
  • API references for more information

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 webhook event payload:

{
  "event_id": "42f14eec-d1dc-11ea-8bbb-080027c1cea9",
  "event_type": "engagement",
  "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",
  "device_type": "Desktop",
  "webhook_guid": "W0123456789",
  "organization_guid": "O1234567890",
  "group_guid": "B0123456789",
  "tags": [
    "tagA",
    "tagB"
  ],
  "time_zone": "America/New_York",
  "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

If Bitly receives two failures from the same webhook event, we will set the webhook to alert status and send a notification email to account admins. A webhook event failure in this context is defined as a client timeout, or 5xx status code response.

The first event failure is ignored, and the event is requeued. Each webhook event will make five total attempts to send a payload to the designated URL endpoint. After the fifth attempt, the event payload will not be requeued, re-sent, or stored for download and is discarded.

Webhooks in alert status will have 24 hours to correct the issue before deactivation. To clear the alert automatically, a webhook event must return a successful 2xx response within the 24 hours. No notification email will be sent if the alert is cleared. If the webhook is deactivated, another notification email will be sent to account admins. Once a webhook is deactivated, it will need to be reactivated manually through the web app or through the Update Webhook API endpoint.

Example webhook error scenario detailed:

  1. A webhook event is triggered by an engagement action in Bitly.

  2. Bitly sends an HTTP request with the event payload to the URL in the webhook's settings.

  3. This first attempt fails, meaning Bitly receives a 5xx response status code or the request surpasses our 10 second timeout limit.

  4. Bitly requeues the request, and it is resent after a delay which is determined by an exponential backoff pattern.

  5. The event fails the 2nd send attempt.

  6. Bitly sets the webhook to an alert status and sends an email to your admins.

  7. Bitly makes a 3rd, 4th, and 5th attempt to send the event.

  8. All 5 attempts have failed, the event is not requeued, and it is not stored.

  9. Bitly waits for a successful webhook event.

  10. After 24 hours has past since the webhook was set to alert status, the first webhook event after this moment will determine if it is deactivated. If the first event after succeeds, we clear the alert. If the event fails, we deactivate the webhook and send an email to your admins.