# 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](/standardize/scorecards.md), [CQL queries](/standardize/cql.md), and on [entity detail pages](/ingesting-data-into-cortex/entities-overview/entities/details.md).
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](/ingesting-data-into-cortex/entities-overview/entities.md#cortex-tag) in the URL if you do not have access to the Cortex tag or the ability to add authentication headers.
{% hint style="info" %}
You can also add custom metadata manually to an entity descriptor or programmatically via the API. Learn more in [Adding custom data](/ingesting-data-into-cortex/entities-overview/entities/custom-data.md).
{% endhint %}
Below the instructions, see an example demonstrating how to [send additional GitHub metadata into Cortex via webhook](#example-github-webhook).
## 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**](https://app.getcortexapp.com/admin/integrations#integration-category-custom).
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](/ingesting-data-into-cortex/entities-overview/entities.md#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](#step-2-send-data-to-the-webhook) 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](#changing-the-mappings-for-entities).
* **Key**: Enter the custom metadata key.
* Data will be stored under the key for entities, similar to adding data via [entity descriptor](/ingesting-data-into-cortex/entities-overview/entities.md#defining-entities-via-yaml-file) or [API](/api/readme/custom-data.md).
* In the [example below](#step-2-post-json-with-curl), 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:
```json
{
"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 `
* 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](#step-1-configure-the-custom-integration-in-cortex).
### **Changing the mappings for entities**
If the webhook payload does not contain a value that maps to the exact [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities.md#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](/ingesting-data-into-cortex/entities-overview/entities.md#defining-entities-via-yaml-file). For example:
```yaml
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](/ingesting-data-into-cortex/entities-overview/entities/custom-data.md), custom integration data appears in the sidebar on an [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details.md) 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](/ingesting-data-into-cortex/integrations/github.md), 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](#step-1-configure-the-custom-integration-in-cortex) 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](/ingesting-data-into-cortex/entities-overview/entities/details.md), click **Custom data & metrics** from the entity's sidebar.
* Next to the `githubTest` key, you will see the payload sent from GitHub:\\
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.cortex.io/ingesting-data-into-cortex/integrations/webhook.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.