Custom webhook integrations

You can create custom integration endpoints to POST arbitrary JSON payloads to Cortex. This can be done without auth or an explicit entity tag in the URL if you do not have access to the entity tag or the ability to add authentication headers.

With this method, you can tell Cortex how to process the payload and map it to an entity. For example, the payload may include a data.tag field that corresponds to the entity tag. This data can also be used within CQL queries.

You can create custom webhook integrations in the UI or via API.

Learn about adding custom data to entities in Adding custom data.

How to create a custom integration endpoint

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 service codeTag from the data, e.g., .data.codeTag. This tells Cortex where in the body we can find the service tag.

     • If the tag Cortex extracts from the payload is not identical to the entity tag in Cortex, the endpoint will throw a 400.

   • Key: Enter the unique key that will be used in CQL queries using the syntax integration(key).

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

4. Click Save.

5. Copy the provided webhook URL to post JSON with cURL.

Changing the mappings for entities

If the webhook payload does not contain a value that maps to the exact entity tag, you can tell Cortex alternative mappings to look up when processing payloads.

x-cortex-custom-integration-mappings:
  - left-brain
  - right-brain

When processing a payload, Cortex takes the output of the Entity tag JQ field in step 2 above and searches for an entity with that value as a 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.