Custom webhook integrations

Custom webhook integrations allow you to POST data to a unique endpoint in Cortex, map the payload to existing entities, and make that data available for use in Scorecards, CQL queries, and on entity detail pages.

Using a custom webhook is especially helpful if:

• You have internal tools, homegrown systems, or third-party services that Cortex doesn't integrate with yet.

• You want to automate the process of sending custom metrics, events, or other data into Cortex without building and maintaining additional infrastructure.

• You want to pre-process data before it reaches Cortex, such as adding extra metadata or transforming the payload format.

This can be done without auth or an explicit Cortex tag in the URL if you do not have access to the Cortex tag or the ability to add authentication headers.

Below the instructions, see an example demonstrating how to send additional GitHub metadata into Cortex via webhook.

How to create a custom webhook integration in Cortex

Step 1: Configure the custom integration in Cortex

1. In Cortex, navigate to Settings > Custom integrations.

2. Click +Add custom integration.

   
3. Configure the integration details:

   • Integration name: Enter a name for the integration.

   • Entity tag JQ: Enter the JQ that will be used to extract the entity's Cortex tag from the data. This tells Cortex where in the payload body we can find the Cortex tag.

     • For example, the payload shown in Step 2 would have .data.codeTag as the JQ, and frontend-service would be the entity's Cortex tag.

     • If the tag Cortex extracts from the payload does not match an existing Cortex tag, it will result in a 400 error and the custom metadata will not be updated. Learn about alternate mappings below.

   • Key: Enter the custom metadata key.

     • Data will be stored under the key for entities, similar to adding data via entity descriptor or API.

     • In the example below, the key is mydata.

4. Click Save.

5. Copy the provided webhook URL.

Step 2: Send data to the webhook

Note that the entity must exist in Cortex before you send the payload.

cURL is a quick and flexible method to post to the webhook and verify that it's receiving data.

1. Save your payload as a .json file. Include the field that matches the JQ expression configured in the previous steps, so Cortex can map the data to the correct entity. For example, the payload might look like this:

{
  "data": {
    "codeTag": "frontend-service",
    "mydata": "4"
  }
}

1. In your terminal, use cURL to POST the JSON, using a command similar to the following: curl -X POST -H "Content-Type: application/json" --data <path to json file> <webhook URL>

   • For example: curl -X POST -H "Content-Type: application/json" --data @/tmp/payload.json https://api.getcortexapp.com/api/v1/custom-integrations/data/12345abcdef

After sending data, the JSON payload is written to the entity's key that you configured for the custom webhook in Step 1.

Changing the mappings for entities

If the webhook payload does not contain a value that maps to the exact Cortex tag, you can configure alternative mappings to look up when processing payloads. Use the x-cortex-custom-integration-mappings block in the entity descriptor YAML. For example:

x-cortex-custom-integration-mappings:
  - frontend
  - brain-service

When processing a payload, Cortex takes the output of the Entity tag JQ field in Step 1 above and searches for an entity with that value as a Cortex tag. If no such entity exists, Cortex checks whether an entity has registered the value as an alternative mapping; if so, the payload is attached to that entity.

View custom integration data in Cortex

Similar to when you add custom metadata to an entity, custom integration data appears in the sidebar on an entity details page within the Custom data & metrics page. It appears with an INTEGRATION tag next to the key name.

Example: GitHub webhook

In this example, we create a webhook integration to send GitHub data into Cortex.

While Cortex does offer a native integration with GitHub, there may be scenarios where you want to send additional metadata that isn't included in the native integration.

1. Create a custom webhook integration in Cortex.

   • Enter a descriptive name so others understand the purpose of this webhook, such as "GitHub metadata."

   • In this example, we use the Service query .repository.name and the Key githubTest.

2. Copy the webhook URL generated in Cortex for this integration.

3. In GitHub, under Settings > Webhooks, create a webhook.

   • In the webhook's settings under Payload URL, paste in the webhook URL from Cortex.

   • Set the Content type to application/json.

4. Push a commit to your GitHub repository.

   • In your GitHub settings under Webhooks, click the Recent Deliveries tab to see the payload that will be sent. Because you set the JQ query to .repository.name, the repository name value in the payload will correspond with the Cortex tag in Cortex. In the example screen shot, the repository name is "michigan":

     
5. Navigate to the entity in Cortex.

   • In this example, the repository name is "michigan," so we can search in Cortex to find an entity with "michigan" as its Cortex tag.

6. On the entity's details page, click Custom data & metrics from the entity's sidebar.

   • Next to the githubTest key, you will see the payload sent from GitHub: