# Guide for Configuring the External Service Incident Custom on the Elven Platform
The **External Service Incident Custom** feature allows you to connect your API to the **Elven Platform** in a practical and efficient way. With this functionality, your API can send data directly to the platform using a URL specifically generated for this purpose. This data can be used to open **custom incidents**, allowing you to monitor events or critical situations in an automated manner. It’s a simple way to integrate your system with the platform, ensuring a quick response aligned with your needs.
In addition, you can also send **status updates**, such as issue resolution. This means that as soon as an incident is handled in your API, the status can be automatically updated in the **Elven Platform** to **Resolved**. This integration reduces manual effort and improves visibility into the workflow, providing more control and peace of mind in managing your services. With this flexibility, the **External Service Incident Custom** adapts perfectly to your environment, putting you in control of your operations.
## **Accessing External Service Incident Custom**
* **Navigate** to the **main menu** and **click** on **Services Hub**.
* In **External Services Monitoring**, select the item **Incident Custom**.
## **Configuring API Token**
To **configure** the **External Service Incident Custom**, it is necessary to **generate** an **API Token**. This token will be included directly in the **URL** as part of the **authentication**, serving as an essential **security item** to ensure that only **authorized users** can access and interact with the **external service**.
* In the **top menu**, under your **user settings**, **click** on **Organization Settings**.
* In the **API tab**, **click** the **+ button** to **create** a new **API Token**.
## **External Service Incident Custom configuration**
The **configuration** of the fields in **External Service Incident Custom** is an essential step to ensure that your **incident notifications** work efficiently and reach the right people at the right time.\
The first field, **External Service Name**, is where you should assign a name to the service being integrated. This name will appear in **dashboards** and **reports**, making it easier to quickly identify the service among others. Choose a clear and descriptive name, as it will be your reference for managing and reviewing the **incident history** in the future.
The **Responders** field is the bridge between the **incident** and the **problem resolution**. Here, you define who will be notified when the incident is triggered—whether specific individuals, entire teams, or even automated systems. This field is vital to ensure that **incident notifications** reach the right people, avoiding delays and confusion. Add relevant contacts, such as **emails** or **team IDs**, and make sure all responsible parties have the necessary information and access to act quickly.\
With this configuration, you turn incidents into immediate and effective actions, ensuring a smooth and reliable experience for everyone involved.
## **External Service Incident Custom URL**
When configuring an **External Service Incident Custom**, one of the most important steps is selecting the **API Token** you previously generated. This key acts as a unique credential that securely connects your system to the **incident notification service**. Think of it as a “**master key**” that enables **authentication** and **communication** between platforms. Make sure to choose the correct **API Token** and keep it protected, as it is essential for the service to function and to ensure the integrity of the integration.
After selecting the **API Token**, you will gain access to the **External Service Incident Custom URL**, which is generated automatically. This **URL** will be used to send **incident notifications** to **Elven Platform**. It’s important to store this **URL** carefully and share it only with authorized people or systems. With this configuration, you ensure that incidents are delivered efficiently, creating a reliable experience for the teams involved and reducing potential disruptions or communication failures.
Additionally, when configuring an incident in **External Service Incident Custom**, it’s important to correctly fill in some **key fields** to ensure the system works effectively. The **action** field must be filled with the values “**alarmed**” (to open an incident) or “**resolved**” (to indicate the incident has been resolved). The **external\_aggregate\_key** field acts as a **unique identifier** for the incident and is required for both actions, as it links the opening and resolution information. Furthermore, the **severity** field defines the **incident’s criticality** and must be filled with one of the available options: **critical**, **high**, **moderate**, **low**, or **informational**. Also, in the **tags** field, you can add information that helps identify the **origin of the incident**. This facilitates **categorization** and **tracking**, making analysis faster and more efficient. Filling in these fields correctly helps ensure **clear and effective communication** between systems, allowing teams to prioritize responses based on the **severity** and **status** of the incident.
### **Here is an example of a CURL command for the custom integration**:
```
curl --request POST \
--url '' \
--header 'Content-Type: application/json' \
--header 'User-Agent: 1PcustomAuth/1.0' \
--data '{
"title": "",
"description": "",
"external_aggregate_key": "001",
"action": "alarmed",
"severity": "",
"tags": [
{
"name": "tag-00",
"value": "value0"
},
{
"name": "tag-01",
"value": "value1"
},
{
"name": "tag-02",
"value": "value2"
}
]
}'
```
* **url**: **API\_URL** generated during the creation of the **External Service**.
* **title**: Defines the **title** of the incident that will appear in **Elven Platform**.
* **description**: **Description** of the incident, which will be displayed as the “cause” in **Elven Platform**.
* **external\_aggregate\_key**: **Identifier** used to “open” and “close” the incident. It must be the same for both actions.
* **action**: **Action** performed, such as “**alarmed**” (to open) or “**resolved**” (to close) the incident.
* **severity**: Defines the **severity** of the incident (**informational**, **low**, **moderate**, **high**, **critical**).
* **tags**: Use the **tags** field to identify the **origin** of the incident and facilitate its analysis.
Once configured, the service will appear in the **External Services Monitoring Center**, categorized by **status**, making it easier to monitor incidents with priority given to those in an **alarmed** state.
## **Additional security and performance settings**
* **Whitelist of IPs**: **API communication** can be configured to allow only **authorized IPs**. To enable or modify this setting, contact **Elven Platform support**.
* **Rate Limiting**: The default **request limiting time** is **5 minutes**, but it can be adjusted as needed. For changes, contact **Elven Platform support**.
These settings ensure greater **security** and **control** over the **data traffic** between integrated systems.
## **Glossary of Technical Terms**
**API Token**: A unique **credential** used to **authenticate** and **authorize** communication between your API and **Elven Platform**. Included in the **URL** generated for authentication and data submission to the external service.
**External Service Incident Custom**: A feature of **Elven Platform** that allows integration with external APIs for sending **incident notifications** and **status updates**. Automates the monitoring of critical events and enables efficient **incident management**.
**External Service Name**: The **name** assigned to the integrated service. Identifies the service in the platform’s **dashboards** and **reports**.
**Responders**: Individuals, teams, or systems responsible for responding to triggered **incidents**. Automatically notified to resolve incident-related issues.
**External Service Incident Custom URL**: Automatically generated **address** for sending **incident notifications** to the integrated service. Connects your API to **Elven Platform’s incident system**.
**Organization Settings**: Menu in **Elven Platform** where **API tokens** can be generated and managed. Location for creating new tokens for authenticating external services.
**title**: **Title** of the incident that will be displayed in **Elven Platform**. Provides a clear and quick view of the nature of the incident.
**description**: **Detail** of the incident, shown in the “cause” field in **Elven Platform**. Provides additional context for analysis and problem resolution.
**external\_aggregate\_key**: Unique **identifier** used to associate actions like “open” and “close” incidents. Must be the same in both actions to maintain consistency in **incident management**.
**action**: **Action** performed on the incident, such as “**alarmed**” (open) or “**resolved**” (close). Indicates the current **status** of the incident in the system.
**severity**: **Severity level** of the incident, which can be **informational**, **low**, **moderate**, **high**, or **critical**. Helps prioritize the response based on the incident’s severity.
