Page Contents

Overview

Bintray exposes a Firehose Events API endpoint that allows the admin or owner of an Enterprise organization to receive notifications for a variety of interactions with its repositories. Notifications are provided in JSON format through a live stream delivered over an open HTTP connection. The purpose of this API is to provide organizations with data transparency and allow them to respond when users interact with the organization or its repositories. As a REST API, the response may be hooked into an organization’s systems for fully automated handling of any of the supported interactions. For example, repeated failed login attempts may trigger an email alert to all the organization’s administrators, while a successful package download may trigger an email sent out to engage the downloading user. Currently, you may register to receive notifications for the following interactions:

  • Uploading a file/artifact

  • Downloading a file/artifact

  • Deleting a file/artifact

  • Successful and failed logins (for scoped users only)

If your organization is not yet on an Enterprise plane, you can upgrade on Bintray’s Pricing page.

Working with Firehose Events API Connections

You may maintain up to 3 live connections to the Firehose API for each Bintray organization. For each open connection, Bintray will stream data in JSON format using chunked encoding for all the monitored events described above. To improve performance, Bintray will compress the stream if you provide the Accept-Encoding: gzip header. In this case, the response header will include a Content-Encoding: gzip element. It is up to you to read the data and respond to it accordingly.

Monitoring Connections

Every 30 seconds, Bintray sends a "keepalive" message ("\r\n") to each open connection to indicate that the connection is alive and functioning. In addition, the response headers include an X-Bintray-Hose-Reconnect-Id element containing a reconnection ID. If the monitoring process does not receive a keepalive message on time, it means the connection is lost. Since Bintray maintains notifications in a queue for a fixed time period, if you reconnect to the Firehose API specifying the reconnect ID within one minute of the last keepalive message, you will get all messages that got backed up in the queue while the connection was down. If you reconnect to the Firehose API without the reconnect ID, you may need to wait for two minutes before a new connection can be established, and all messages backed up from the old connection will be lost.

Usage Through JFrog CLI

The Firehose API is wrapped by a call in JFrog CLI, so while you may use the Firehose Event API directly, we recommend accessing it via JFrog CLI. Working through JFrog CLI offers two main advantages:

  • Automatic reconnect
    If your live connection to Bintray goes down for any reason, JFrog CLI will automatically reconnect using the X-Bintray-Hose-Reconnect-Id header flag to ensure none of your events are lost.

  • Event Filtering
    JFrog CLI lets you specify which events you are interested in and can filter the rest out.

Accessing the Firehose Event API through JFrog CLI is very simple. The basic command is of the form:

> jfrog bt stream ...

For full details on how to use the Firehose Events API through JFrog CLI, please refer to the JFrog CLI User Guide

Event Responses

Event response JSON structures contain the following fields:

Field

Description

"type"

Describes the event type. May be one of "upload", "download", "delete", "login_success", "login_failure"

"path"

The path to the artifact that generated the event. Not provided in login events

"subject"

Bintray user that generated the event

"time"

When the event happend in ISO8601 format (yyyy-MM-dd’T’HH:mm:ss.SSSZ)

"ip_adress"

The IP of the machine that generated the event

"user_agent"

The user agent of the tool that generated the event

"content_length"

The size (in bytes) of the artifact that generated the event. Only provided in download events

Below are some sample event responses:

Upload

{
  "type": "upload",
  "path": "/myorg/mavenp/app.jar",
  "subject": "user",
  "time": "2016-12-05T06:33:49.818Z",
  "ip_address": "72.81.195.4",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36"
}

Download

{
  "type": "download",
  "path": "/myorg/mavenp/app.jar",
  "subject": "user",
  "time": "2016-12-05T06:34:00.825Z",
  "ip_address": "72.81.195.4",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36",
  "content_length": 33465
}

Delete

{
  "type": "delete",
  "path": "/myorg/mavenp/app.jar",
  "subject": "user",
  "time": "2016-12-05T06:34:06.532Z",
  "ip_address": "72.81.195.4",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36"
}

Login success

{
  "type": "login_success",
  "time": "2016-12-05T06:32:42.987Z",
  "subject": "user@myorg",
  "ip_address": "72.81.195.4",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36"
}

Login fail

{
  "type": "login_failure",
  "time": "2016-12-05T06:33:01.011Z",
  "subject": "user@myorg",
  "ip_address": "72.81.195.4",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36"
}