Custom webhook integrations

• 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.

​

How to create a custom webhook integration in Cortex

​

Step 1: Configure the custom integration in Cortex

1. In Cortex, navigate to Integrations. On the left side of the Integrations page, click 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

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"
  }
}

2. 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

​

Changing the mappings for entities

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

​

View custom integration data in Cortex

​

Example: GitHub webhook

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: