API Reference

Events API

Using the Events API

The Events API is a streamlined, easy way to build apps that respond to activities in Asset Management for Jira. All you need is a secure place for us to send your events.

Benefits of using the Events API

  • No need to poll continuously.
  • Receive events that you care about.

Event loop

Apps that are built using the Events API will follow the same abstract event-driven sequence:

  1. A user creates a circumstance that triggers an event subscription to your application
  2. Your server receives a payload of JSON describing that event
  3. Your server acknowledges receipt of the event
  4. Your business logic decides what to do about that event
  5. Your server carries out that decision

Subscribing to event types

To begin working with the Events API, you need to to Settings Page and Enable Events from the Events tab.

1912

Events Request URL

Your Events API Request URL is the target location where all the events your application is subscribed to will be delivered.

Your Request URL will receive JSON-based payloads containing wrapped event types. The volume of events will vary depending on the events you subscribe to.

📘

Best Practice

Your Request URL might receive many events and requests. Consider decoupling your ingestion of events from the processing and reaction to them.

Choosing event subscriptions

We currently offer the following event subscriptions:

  • asset.create: A new asset was created
  • asset.update: An existing asset was updated
  • asset.delete: An existing asset was deleted

Receiving Events

Your Request URL will receive a request for each event matching your subscriptions. One request, one event.

The event will be in the Content-Type: application/json format. The schema of the event will be as follows:

Field NameTypeDescription
event_typestringSubscription that triggered event (asset.create, asset.update, asset.delete)
namestringName of asset
assettypedictContains id and name of asset type associated with asset
locationdictContains id and name of location associated with asset
loaneedictContains id and name of loanee associated with asset
field_valuesarrayDetails about the custom asset fields associated with the asset
{
  "field_values": [
    {
      ...
    }
  ],
  "created_at": "2022-09-14 03:03:44.456537",
  "id": 675,
  "location": {
    "id": 50,
    "name": "My IT Office"
  },
  "name": "Spare-02",
  "assettype": {
    "id": 86,
    "name": "2 in 3 Laptop"
  },
  "loanee": {
    "id": 142,
    "name": "John Do"
  },
  "updated_at": "2022-11-11 05:05:07.302773",
  "event_type": "asset.update"
}

Responding to Events

Your app should respond to the event request with an HTTP 2xx within three seconds. If it does not, we'll consider the event delivery attempt failed. After a failure, we'll retry three times, backing off exponentially.

If 3 consecutive events fail to get a successful response, we will automatically disable delivery of any future events.

Resuming event deliveries

You can manually re-enable event subscriptions by visiting your application's settings.