What are Webhooks?

Webhooks allow you to receive information about events as they happen in near real-time in LeanIX. You can then extend, customize, and integrate LeanIX with your own extensions or even with other applications. LeanIX can deliver events in two ways:

PUSH – Events are sent as HTTP POST requests to a server provided by you. This is commonly described as a webhook, e.g. on the PBWiki Webhooks page. It is the preferred way to receive LeanIX events.
PULL – If an environment does not allow exposing a public HTTP server to receive events, they can also be retrieved by repeatedly calling a REST endpoint on the LeanIX API. This way of polling events is helpful e.g. when your application is running behind a firewall. Events are retained on the server for 30 days, but it is recommended to retrieve them more regularly.

We have built our own Slack Bot using Webhooks, check out the example here.

To test PUSH Webhooks before setting up scripts, the Webhook Tester tool is an excellent utility that helps you see data come across as various events happen in our system. To test PULL Webhooks manually, a command line HTTP client like curl can be used.

Configuring Webhooks

Webhooks are configured in the LeanIX Administration. Here are the basic steps:

Log in to LeanIX account
Navigate to Administration
Click on "Webhooks" in the sidebar
Click the "New webhook" button

Configuration is simple: Select the event types you want to receive, provide an optional name and select the desired delivery type. Depending on the delivery type, different options are available.

Event Types and Payloads

We'll return various data based on each event type. Below is sample data for each event type. You can also see this using the Webhook Tester tool mentioned above.

FACT_SHEET_CREATED – New Fact Sheet is created (or recovered from archive)
FACT_SHEET_UPDATED – Fact Sheet is updated (incl. one of the relations)
FACT_SHEET_ARCHIVED – Fact Sheet is archived
FACT_SHEET_DELETED – Fact Sheet is deleted (e.g. when a Fact Sheet type is removed completely from the data model)

In general, the payload for the above event types contains information on the event, the user which triggered the event, meta information such as the type of the Fact Sheet and the actual Fact Sheet data like fields and relations.

{
  "createdAt": "2017-12-20T12:24:33Z",
  "factSheet": {
    "completion": "{...}",
    "createdAt": "2017-12-20T12:24:32.913Z",
    "displayName": "Webhooks Example",
    "documents": "[...]",
    "fields": "[...]",
    "fullName": "Webhooks Example",
    "id": "62c40a1a-7626-45b9-a6d0-4a399df32a09",
    "level": 1,
    "naFields": "[...]",
    "name": "Webhooks Example",
    "relations": "[...]",
    "rev": 0,
    "status": "ACTIVE",
    "subscriptions": "[...]",
    "type": "Application",
    "updatedAt": "2017-12-20T12:24:32.915Z"
  },
  "id": 5660,
  "transactionSequenceNumber": 65871,
  "type": "FactSheetCreatedEvent",
  "userId": "c5dc97b3-7c1d-42c1-b0b5-dc8be4e06030",
  "workspaceId": "cdc70f10-be33-48ed-bd66-e20028d0e6f4"
}

{
  "createdAt": "2017-12-20T12:25:04.572Z",
  "factSheet": {
    "completion": "{..}",
    "createdAt": "2017-12-20T12:24:32.913Z",
    "displayName": "Webhooks Example",
    "documents": "[...]",
    "fields": [
      {
        "data": {
          "keyword": "businessCritical",
          "type": "SingleSelect"
        },
        "dataType": null,
        "name": "businessCriticality"
      },
      {
        "data": {
          "type": "StringValue",
          "value": "Example Description"
        },
        "dataType": null,
        "name": "businessCriticalityDescription"
      }
    ],
    "fullName": "Webhooks Example",
    "id": "62c40a1a-7626-45b9-a6d0-4a399df32a09",
    "level": 1,
    "naFields": "[...]",
    "name": "Webhooks Example",
    "relations": "[...]",
    "rev": 2,
    "status": "ACTIVE",
    "subscriptions": "[...]",
    "type": "Application",
    "updatedAt": "2017-12-20T12:25:04.540Z"
  },
  "id": 5668,
  "transactionSequenceNumber": 65885,
  "type": "FactSheetUpdatedEvent",
  "userId": "c5dc97b3-7c1d-42c1-b0b5-dc8be4e06030",
  "workspaceId": "cdc70f10-be33-48ed-bd66-e20028d0e6f4"
}

{
  "affectedFactSheetIdAndRev": [
    {
      "id": "62c40a1a-7626-45b9-a6d0-4a399df32a09",
      "rev": 2
    }
  ],
  "comment": "Example Comment",
  "createdAt": "2017-12-20T12:25:29.165Z",
  "fsIdAndRev": {
    "id": "62c40a1a-7626-45b9-a6d0-4a399df32a09",
    "rev": 2
  },
  "id": 5670,
  "transactionSequenceNumber": 65890,
  "type": "FactSheetArchivedEvent",
  "userId": "c5dc97b3-7c1d-42c1-b0b5-dc8be4e06030",
  "workspaceId": "cdc70f10-be33-48ed-bd66-e20028d0e6f4"
}

{
  "createdAt": "2017-12-20T15:00:11.768Z",
  "fsIdAndRev": {
    "id": "62c40a1a-7626-45b9-a6d0-4a399df32a09",
    "rev": 2
  },
  "id": 5672,
  "transactionSequenceNumber": 65895,
  "type": "FactSheetDeletedEvent",
  "userId": "c5dc97b3-7c1d-42c1-b0b5-dc8be4e06030",
  "workspaceId": "cdc70f10-be33-48ed-bd66-e20028d0e6f4"
}

Error handling

In case the Target URL is not reachable, misconfigured or responses with a http status different than 200, 202 and 204, webhooks retries to deliver the event after 50 seconds again and again until the delivery was successful. Webhooks always tries to guarantee each event reaches the configured Target Url.
In case the user has activated the Ignore Errors check box this behavior changes and all those events will simply omitted.

If your webhook delivery log shows the error java.lang.IllegalStateException: Already Executed, it is very likely that your processing logic took a long time and it did not complete before the webhook retry interval. Please make sure that your processing logic returns an http status before the webhook delivery is retried.

🚧
Automatic deactivation
In order to save CPU usage, webhooks deactivates automatically all subscriptions which points to a Target URL that is not reachable or responses with a non-successful http code for more than 10 days. This means a subscription with a "broken" target endpoint will be deactivated after 10 days and the admin needs to activate the subscription manually after its configured Target URL works again.

Advanced: Access further Event Types

Beside the listed event types, we have other event types available that are currently not configurable via the UI. Instead, please use the /services/webhooks/v1/subscriptions endpoint for this, e.g.

curl --request POST \
  --url https://app.leanix.net/services/webhooks/v1/subscriptions \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJz [...]'
  --data '{
    "deliveryType": "PULL",
    "tagSets": [
      [
        "pathfinder",
        "FACT_SHEET_CREATED"
      ]
    ],
    "workspaceId": "<WS_ID>"
  }

Examples of other available events are fact sheet views ( ["pathfinder", "FACT_SHEET_VIEWED"] ) or configuration events ( ["integrations", "CONFIGURATION_CREATED"],["integrations", "CONFIGURATION_UPDATED"], ["integrations", "CONFIGURATION_DELETED"], ["integrations", "CONFIGURATION_ACTIVATED"].

{
  "createdAt": "2017-12-20T12:24:33Z",
  "factSheetId": "8e421182-06d7-4b25-9740-d8a4bae2d75c",
  "id": 5660,
  "transactionSequenceNumber": 65871,
  "type": "FactSheetViewedEvent",
  "userId": "c5dc97b3-7c1d-42c1-b0b5-dc8be4e06030",
  "workspaceId": "cdc70f10-be33-48ed-bd66-e20028d0e6f4"
}

{
  "type":"CONFIGURATION_CREATED",
  "userId":"64875bf3-76e2-4378-a2fb-9f8ea74d2b20",
  "connectorId":"foobar",
  "workspaceId":"2fe9d275-50cb-418d-b6ec-7e4723a25422",
  "connectorType":"baz",
  "processingMode":"partial",
  "integrationType":"Integration API",
  "connectorVersion":"1.0.0",
  "processingDirection":"inbound"
}

{
  "type":"CONFIGURATION_UPDATED",
  "userId":"64875bf3-76e2-4378-a2fb-9f8ea74d2b20",
  "connectorId":"foobar",
  "workspaceId":"2fe9d275-50cb-418d-b6ec-7e4723a25422",
  "connectorType":"baz",
  "processingMode":"partial",
  "integrationType":"Integration API",
  "connectorVersion":"1.0.0",
  "processingDirection":"inbound",
  ...
}

{
  "type":"CONFIGURATION_DELETED",
  "userId":null,
  "connectorId":"foobar",
  "workspaceId":"2fe9d275-50cb-418d-b6ec-7e4723a25422",
  "connectorType":"baz",
  "processingMode":"partial",
  "integrationType":"Integration API",
  "connectorVersion":"1.0.0",
  "processingDirection":"inbound"
}

{
  "type":"CONFIGURATION_ACTIVATED",
  "userId":"64875bf3-76e2-4378-a2fb-9f8ea74d2b20",
  "connectorId":"foobar",
  "workspaceId":"2fe9d275-50cb-418d-b6ec-7e4723a25422",
  "connectorType":"baz",
  "processingMode":"partial",
  "integrationType":"Integration API",
  "connectorVersion":"1.0.0",
  "processingDirection":"inbound"
}

Web hooks for event-types not available in the UI can be created through the REST API using the following steps.

Create a web hook through the UI at /admin/webhooks. It does not matter which Triggering Event you select from the drop down, as this event will simply serve as a template.
Generate an API token for your Workspace within Pathfinder (Admin > API Tokens)
Navigate to services/webhooks/v1/docs/. Input the API Token generated in Step 2 in the API token field and click Explore.
Copy the Subscription ID of the WebHook created in Step 1 and input it as the ID parameter of the getSubscription call. Click ‘Try it Out!’ to run the call. A successful call will return a Response Code of 200 and the Response Body will contain JSON data reflecting the configurations of the web hook created in Step 1.

Copy only “data” object of the of the Response Body, excluding the ‘“data”: ’, and paste it in a text editor to be modified in the following ways:

    a. Remove the “id” field 

    b. Replace the event type in the tagSets array with your desired event type. A list of available event types can be found below under ‘List of Webhook Events’

    c. Update the "identifier" of the call to reflect the name of the new web hook to be created

Copy modified data and paste it as the Subscription Value for the createSubscription call. Run the call by clicking Try it Out! A successful call will return a Response Code of 200. You can also confirm the newly created web hook by navigating to admin/webhooks within your pathfinder workspace.

Using PUSH Webhooks

For events to be delivered using PUSH, a Target URL needs to be configured for the Webhook. An HTTP POST requests with the event payload in the body will be sent to this URL every time an event occurs in LeanIX. Your server is expected to return an HTTP status code of 200 to signal that an event was received successfully. The results for event deliveries from the last 30 days are listed on the Webhook details page, below the configuration fields.

Security

For the target URL, we support either HTTP or HTTPS, so you can have security by using an SSL-enabled URL. Please remember that your endpoint is going to be wide-open on the internet, and you might not want others to be able to submit random data to your systems. At this time, aside from trying to keep the URL private we recommend two ways to protect your Webhooks endpoint:

A. Make use of the Authentication-Header which we allow to be set, e.g. using Basic Auth.
B. Append a token to the query string of the URL which you check in your code.

Advanced: Manipulate Payload using Callback

We provide an option to define a callback which allows you to manipulate the payload using JavaScript code before it is sent out to the defined URL. See our example of the LeanIX Slack Bot as a great use case which makes use of this callback.

Within the JavaScript code, the object delivery is available in the global scope. It has, among others, the properties payload, targetMethod or targetUrl. You can manipulate these properties right from your code.

var payload = delivery.payload;

delivery.targetMethod = 'POST';
delivery.targetUrl = delivery.targetUrl += '?test=1';

delivery.payload = {
  text : 'Hello World'
};

A common manipulation is to restrict webhook generation to just a single factsheet type. For example, if webhooks should only be produced for Applications, this can be achieved with the following code:

delivery.active = false;

if (delivery.payload.factSheet.type == 'Application' ) {
   delivery.active = true;
}

Be aware, that for performance reasons, we cache the evaluation context of the callback of your subscription for a certain amount of time. Make sure to initialise new variables correctly, because otherwise they might still contain the assign value from a previous callback execution of your subscription.

📘
JavaScript Supported
Webhooks use the Nashorn Engine version 15.3
It is compatible with ECMAScript 5.1 also many new features from ECMAScript 6 more details in the documentation.

Using PULL Webhooks

When events are retrieved using PULL, there is only one additional configuration option: maxBatchSize. It defines a soft upper limit for the amount of data in each batch of events. Usually, batches will contain less than the specified amount of data. However, when a single event exceeds the given value, it will be delivered anyways. By default, maxBatchSize is set to 512 kB.

Retrieving Events

For webhooks using PULL, events can be retrieved using an HTTP GET request to the /services/webhooks/v1/subscriptions/<subscriptionId>/events endpoint. As for all requests to the LeanIX API, an access token has to be provided. See the Authentication documentation for details. Please keep in mind that events are retained on the server for 30 days, after this period they are not available for retrieval anymore.

curl --request GET \
  --url https://app.leanix.net/services/webhooks/v1/subscriptions/888eaaf3-c72f-411c-a78a-d382ba9b2f75/events \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJz [...]'

The request will return a JSON result that is shaped as follows:

{
  "data": {
    "events": [
      {
        "event": "{...}",
        "cursor": {
          "offset": 178
        }
      },
      {
        "event": "{...}",
        "cursor": {
          "offset": 179
        }
      }
    ],
    "nextCursor": {
        "offset": 182
    }
  },
  "errors": [],
  "status": "OK",
  "total": 3,
  "type": "PullResult"
}

The event objects themselves are the same as described above. Additionally, each event is annotated with a cursor that can be used later to "rewind" the webhook to the given event. Also, for the whole batch of events, there is a nextCursor.

Moving the Cursor

After retrieving and processing a batch of events successfully, the cursor of the webhook needs to be moved forward. Otherwise, the next GET request would return the same events as before. This is to make sure that even when your application is malfunctioning temporarily, it will eventually receive all events. When all goes well, the cursor should be moved to the given nextCursor, using an HTTP PUT request to the /services/webhooks/v1/subscriptions/<subscriptionId>/cursor endpoint.

curl --request PUT \
  --url https://app.leanix.net/services/webhooks/v1/subscriptions/888eaaf3-c72f-411c-a78a-d382ba9b2f75/cursor \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJz [...]' \
  --header 'Content-Type: application/json' \
  --data '{"offset": 182}'

Alternatively, the cursor can be moved forward automatically when events are retrieved. This behavior can be enabled by adding autoCommit=true as a query string parameter to the GET request above. While this is convenient to use, it cannot guarantee that all events are successfully received and processed by your application, both in case of network issues or problems in your application.

Intended Usage

PULL webhooks are intended to be used in a loop:

make a request to retrieve some events,
process the events,
on success, make a request to advance the cursor (or rely on autoCommit),
reiterate.

The request to retrieve events takes another parameter, timeout, which specifies the number of seconds to wait for events before returning an empty response. This prevents your loop from generating too much traffic when no events are generated in the workspace. The timeout parameter has a minimum allowed value of 1 and defaults to 10. Events will always be returned as soon as possible, the timeout affects only the case when no events after the cursor are currently present.

Concurrency

Please note that due to the cursor mechanism of a PULL webhook and the loop pattern described above, it does not make sense to use the same webhook with several HTTP clients concurrently. While we detect and refuse processing of concurrent requests to the same subscription id, it is ultimately up to the users of a webhook to make sure only one client uses the same webhook. Create one webhook per client.

Webhooks

What are Webhooks?

Configuring Webhooks

Event Types and Payloads

Error handling

🚧
Automatic deactivation

Advanced: Access further Event Types

Using PUSH Webhooks

Security

Advanced: Manipulate Payload using Callback

📘
JavaScript Supported

Using PULL Webhooks

Retrieving Events

Moving the Cursor

Intended Usage

Concurrency

What are Webhooks?

Configuring Webhooks

Event Types and Payloads

Error handling

🚧Automatic deactivation

Advanced: Access further Event Types

Using PUSH Webhooks

Security

Advanced: Manipulate Payload using Callback

📘JavaScript Supported

Using PULL Webhooks

Retrieving Events

Moving the Cursor

Intended Usage

Concurrency

🚧
Automatic deactivation

📘
JavaScript Supported