Configuration Guide for External Service Alert using Custom and Elasticsearch on Elven Platform

The External Service Alert 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 alerts, 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.

Additionally, you can also send status updates, such as issue resolution. This means that as soon as an alert is handled in your API, the status can be automatically updated in the Elven Platform to Resolved. This integration reduces manual effort and improves workflow visibility, providing more control and peace of mind in managing your services. With this flexibility, External Service Alert Custom fits perfectly into your environment, putting you in command of your operations.

Accessing External Service Alert Custom

• Navigate to the main menu and click on Services Hub.

• In External Services Monitoring, select the Alert Custom item.

API Token configuration

To configure the External Service Alert Custom, you need to generate an API Token. This token will be included directly in the URL as part of the authentication process, 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 Alert Custom Configuration

Configuring the fields in the External Service Alert Custom is an essential step to ensure your alerts 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 alerts in the future.

The Responders field is the bridge between the alert and the problem resolution. Here, you define who will be notified when the alert is triggered—whether specific individuals, entire teams, or even automated systems. This field is vital to ensure alerts 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 alerts into immediate and effective actions, ensuring a smooth and reliable experience for everyone involved.

URL of the External Service Alert Custom

When configuring an External Service Alert Custom, one of the most important steps is selecting the API Key you generated earlier. This key acts as a unique credential that securely connects your system to the alert service. Think of it as a “master key” that enables authentication and communication between platforms. Make sure to choose the correct API Key and keep it protected, as it is essential for the service to function properly and to ensure the integrity of the integration.

After selecting the API Key, you will gain access to the External Service Alert Custom URL, which is automatically generated. This URL will be used to send alert notifications to the Elven Platform. It’s important to store this URL carefully and share it only with authorized individuals or systems. With this setup, you ensure that alerts are delivered efficiently, creating a reliable experience for the teams involved and reducing potential disruptions or communication failures.

In addition, when configuring an alert in the External Service Alert Custom, it is 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 alert’s 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. Additionally, in the tags field, you can add information that helps identify the alert’s origin. This facilitates categorization and tracking of alerts, making analysis faster and more efficient. Filling out these fields correctly helps ensure clear and effective communication between systems, allowing teams to prioritize responses based on the incident’s severity and status.

Here is an example of a CURL command for the custom integration:

curl --request POST \
--url '<Elven API URL>' \
--header 'Content-Type: application/json' \
--header 'User-Agent: 1PcustomAuth/1.0' \
--data '{
  "title": "<alert title>",
  "description": "<"alert description>",
  "external_aggregate_key": "001",
  "action": "alarmed",
  "severity": "<alert 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 the Elven Platform.

• description: Description of the incident, which will be displayed as the “cause” in the Elven Platform.

• external_aggregate_key: Identifier used to “open” and “close” the incident. It must be the same for both actions.

• action: Executed action, such as “alarmed” (open) or “resolved” (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 alert and facilitate its analysis.

Configuring Webhooks in ElasticSearch

Configuring a Webhook in ElasticSearch to integrate it with the Elven Platform is a simple task that can be completed quickly with a few steps. The process involves creating a connector in Elastic Cloud and setting its properties to enable communication with the external integration. Let’s break down how to do this clearly and practically.

First, access Elastic Cloud and go to the Stack Management section. Within it, locate the Alerts and Insights area and click on Connectors. This is where we’ll configure the integration that will connect ElasticSearch to the Elven Platform.

In the next step, click on Create Connector and choose the Webhook option. Now it’s time to configure the connector details. Give the connector a name—something that easily identifies its purpose, such as “Elven Platform Webhook”. Then, set the method to POST and enter the URL generated during the creation of the external integration in the URL field.

For this configuration, authentication is not required, so you can uncheck that option. However, remember to add an HTTP header to ensure the integration works correctly. To do this, select the ADD HTTP HEADER option and fill in the fields with the following values:

• Key: User-Agent

• Value: 1PcustomAuth/1.0

With these adjustments completed, click on Save & Test to check if the connector has been configured correctly. On the next screen, it's time to customize the payload that will be sent to the Elven Platform. This payload defines the information that will appear as an alert on the platform.

Fill in the fields as follows:

• title: A title that describes the incident (for example, “Connection Error in Application X”).

• description: An explanatory text about the incident, helping to detail the issue.

• external_aggregate_key: A unique identifier for the incident, useful for grouping related monitoring events.

• action: The type of action, such as Alarmed (for alerts) or Resolved (for resolution).

• organization: The Elven Platform organization ID to which the incident will be associated (must be requested from the Elven Platform Support team).

After filling in the payload body, click Run to perform a test. If everything is configured correctly, you will receive an incident notification in the Elven Platform. This process is essential to ensure that ElasticSearch alerts are efficiently integrated with the Elven Platform, enabling centralized and agile incident management. Once configured, the service will appear in the External Services Monitoring Center, sorted by status, making it easier to monitor incidents with priority given to those in an alarmed state.

Additional security and performance settings

• IP Whitelist: 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 the Elven Platform. Included in the URL generated for authentication and data submission to the external service.

External Service Alert Custom: A feature of the Elven Platform that allows integration with external APIs to send alerts and status updates. Automates the monitoring of critical events and efficiently manages alerts.

External Service Name: The name assigned to the integrated service. Identifies the service in the platform’s dashboards and reports.

Responders: People, teams, or systems responsible for responding to triggered alerts. Automatically notified to resolve issues related to the alert.

External Service Alert Custom URL: Automatically generated address for sending alert notifications to the integrated service. Connects your API to the Elven Platform alert system.

Organization Settings: Menu in the Elven Platform where API tokens can be generated and managed. Used to create new tokens for authenticating external services.

title: The incident title that will be displayed in the Elven Platform. Provides a clear and quick view of the nature of the incident.

description: Incident details, shown in the “cause” field in the Elven Platform. Provides additional context for analyzing and solving the issue.

external_aggregate_key: A 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: The action performed on the incident, such as alarmed (open) or resolved (close). Indicates the current status of the incident in the system.

severity: The severity level of the incident, which can be informational, low, moderate, high, or critical. Helps prioritize the response based on the incident’s impact.

ElasticSearch: A distributed search and analytics engine based on the Apache Lucene library. Widely used to store, search, and analyze large volumes of data in near real-time. It is the core tool within the Elastic Stack, enabling fast and efficient queries on structured and unstructured data.

Elastic Cloud: A cloud-based service that provides access to ElasticSearch and other Elastic Stack tools for data management and analysis.

Stack Management: Section in Elastic Cloud used to manage stack configurations and integrations, such as connectors, alert rules, and monitoring.

Alerts and Insights: A specific area within Stack Management dedicated to configuring alerts, connectors, and data-based insights.

Connectors: Tools that allow ElasticSearch to integrate with external services or platforms to automate notifications and actions based on alerts.

Webhook: A communication method between systems that allows sending information (payloads) from one service to another via HTTP requests.

Create Connector: Option in Elastic Cloud that allows creating new connectors for integration with external services.

Method (POST): One of the HTTP methods used to send data to a server, typically to create or update resources in external systems.

URL: The API address generated by the external integration, used to send ElasticSearch data to the Elven Platform.

Authentication: A mechanism to verify the identity of a user or system. In this case, it is not required for the configuration.

HTTP Header: Additional information sent along with the HTTP request to configure or customize communication between systems.

Key (User-Agent): HTTP header used to identify the client making the request. In this case, it is set as 1PcustomAuth/1.0.

Save & Test: Option to save the connector settings and run a test to verify if the integration is working correctly.

Payload: A set of data sent in an HTTP request to communicate specific information between systems. Here, it defines the incident details.

Title: Field in the payload that defines the alert title, displayed in the Elven Platform.

Description: Field in the payload that provides a detailed description of the event that triggered the alert, helping with context.

External Aggregate Key: Unique identifier for the alert, used to group related monitoring events in the Elven Platform.

Action: Field that specifies the type of action related to the incident, such as Alarmed (when the incident is detected) or Resolved (when resolved).

Organization: ID that identifies the organization in the Elven Platform, ensuring the data is associated with the correct entity. Must be requested from the Elven Platform Support team.