Custom integration framework for webhook integration

Introduction

Use a custom integration framework to create webhook integrations to build data ingestion and capture events in OpsRamp. Use either OpsRamp APIs or user interface to build webhook integration.

Configure using OpsRamp API

Configure webhook integration using OpsRamp API.

API endpoint URL: https://{api-url}/api/v2/tenants/{tenantId}/integrations/install/CUSTOM

Sample alert payload in JSON from third-party applications

{
    "severity" : "Warning",
    "eventDetails" : "Test Description",
    "eventResourceName" : "Test ResourceName 1",
    "eventAlertMetric" : "Test Metric",
    "shortDescription" : "Test API Alert for custom webhook integration"
}

Sample API endpoint URL and payload

Given below is the example payload for the above-mentioned JSON sample webhook event to install a custom integration with Webhook authentication and sample webhook mappings. With this payload, the default Alert Source is saved as Custom.git

{
    "displayName": "API Testing",
    "category": "Monitoring",
    "inboundConfig": {
        "authentication": {
            "authType": "WEBHOOK"
        },
        "mapAttributes": [{
            "name": "Alert state",
            "thirdPartyAttrName": "severity",
            "entityType": "ALERT",
            "thirdPartyEntityType": "Event",
            "attrValues": [{
                "attrValue": "Ok",
                "thirdPartyAttrValue": "Ok"
            }, {
                "attrValue": "Warning",
                "thirdPartyAttrValue": "Warning"
            }, {
                "attrValue": "Critical",
                "thirdPartyAttrValue": "Critical"
            }, {
                "attrValue": "Info",
                "thirdPartyAttrValue": "Info"
            }]
        }, {
            "name": "Alert description",
            "thirdPartyAttrName": "eventDetails",
            "entityType": "ALERT",
            "thirdPartyEntityType": "Event"
        }, {
            "name": "Alert resource name",
            "thirdPartyAttrName": "eventResourceName",
            "entityType": "ALERT",
            "thirdPartyEntityType": "Event"
        }, {
            "name": "Alert metric",
            "thirdPartyAttrName": "eventAlertMetric",
            "entityType": "ALERT",
            "thirdPartyEntityType": "Event"
        }, {
            "name": "Alert subject",
            "thirdPartyAttrName": "shortDescription",
            "entityType": "ALERT",
            "thirdPartyEntityType": "Event"
        }]
    }
}

Configure using web interface

From the OpsRamp console, install a monitoring configuration and configure for webhook authentication.

Install custom integration for Monitoring

1. From All Clients, select a client.
2. Go to Setup > Integrations > Integrations.
3. From Available Integrations, select Other > Custom Integration.
4. Enter the following details and click Install:
   • Name
   • Description
   • Category: Select Monitoring.
   • Alert Source: Select Custom if you do not find the desired source already available on the list. Based on the selection, the alerts are filtered in the OpsRamp Alerts section.
     Note: To add a source on the list to filter alerts, contact OpsRamp support.

     

   • Upload Logo

Configure the custom integration for webhook

The custom integration category allows inbound (Inbound Custom Monitoring to OpsRamp)) communication.

To configure,

1. Select Webhook as Authentication Type.

2. Verify the default Role.
   Note: You can execute only those APIs that are associated with the selected role.

3. Click Save and make a note of Token and webhook URL.
   Note: Both are required while configuring a third-party application.

4. Expand Map Attributes, select OpsRamp Entity Alert from the drop-down available and click + to define mappings.

   • Field mapping: Maps the fields from your application entity attributes to OpsRamp entity attributes.
     Example: If you are trying to integrate events as OpsRamp alerts, then alert subject, alert description, alert time, alert resource, and hostname are field mapping attributes.
   • Field value mappings: If an attribute has multiple values to map, then that attribute falls under field value mappings.
     Example: When trying to integrate events as OpsRamp alerts, then alert state (with values critical, warning, Info) and alert metric are field value mapping attributes.

5. Select Additional settings.

   Note: Admins can configure event ingestion integrations to post events only if the resources are managed by OpsRamp. For resources that are not managed, the events are dropped and not processed.

   

6. Select templates from Monitoring of Integrations if you want to monitor integration failures. See monitoring integration failures for more information.

7. View logs from the Audit Logs tab.
   Note: Logs are visible only after successful API calls.

View Alerts

Validate

Validate the configurations using any API development tool, for example, POSTMAN.

Sample request payload

{
"Alertstate" :"Ok",
"Description":"test description",
"serviceName":"Metric",
"ResourceName":"Host",
"Subject" : "Alert Subject"
}

Post alert through Postman

1. Provide the webhook URL copied from OpsRamp.
2. Change the method to POST.
3. Add the mentioned headers ‘Content-Type: application/json’ and ‘Accept: application/json’.
4. Provide the JSON request payload in the body section.
5. View failure or success result.