Skip to main content

Define a custom integration

Create your own integration (CYOI) lets you use a webhook configured in a third-party service to send events or metrics to APEX AIOps Incident Management.

Note

Before going further, browse the list of topics located under Ingestion methods. Step-by-step instructions are available for configuring custom integrations for several third-party services.

The Integrations > Ingestion Services > Create your own Integration page lists the custom integrations defined in your Incident Management instance. Each integration specifies the following:

  • A user-defined endpoint for ingesting events or metrics from a third-party service.

  • A set of mappings from the third-party metric/event fields to their Incident Management equivalents.

  • A deduplication key that defines the fields used to identify duplicate events.

Before you begin

Before you create a custom integration, do the following:

  • Make sure you are signed in to your Incident Management instance.

  • Make sure that you have a valid Incident Management API key.

  • Make sure you are signed in to your third-party service.

  • Verify that you can create a webhook in your third-party service. Your third-party service must be able to post REST requests with JSON payloads over port 443.

  • Familiarize yourself with the payloads generated by your third-party service and compare them with the Incident Management Events API or Metrics API schema.

    CYOI accepts both JSON and XML payloads. XML payloads are automatically converted to JSON.

Create a custom integration in Incident Management

  1. Within Incident Management, navigate to Integrations > Ingestion Services > Create your own Integration.

  2. Click Add New Integration.

  3. Under APEX AIOps Incident Management Endpoint, enter a unique name for your new integration (required).

    Note

    The name of the integration can be anything you choose. Incident Management will automatically generate an API endpoint URL independent of what you enter for this field.

  4. Under API Description, enter a description for the integration (optional).

  5. Under Data Type, select either Events or Metrics.

  6. Click Save.

  7. Keep the web page for this integration open in your browser while you complete the following steps in your third-party service.

Create a webhook in the third-party service

The steps in this section are only intended to serve as general guidelines. The exact procedure will vary depending on your specific third-party service.

  1. Open your third-party service and create a new webhook. Consult the documentation for your third-party service for instructions on how to create an outbound webhook within their product.

  2. Enter a unique name for the webhook, such as "IMWebhook."

  3. Set the HTTP method to POST.

  4. If you are sending XML events instead of JSON, set the "Content-Type" header to text/xml.

    Multiple XML events can be sent in a single request, just like with JSON-format requests. The incoming XML will be converted to JSON before any mapping occurs. For more information, read Ingesting XML payloads in custom integrations.

  5. Paste your Incident Management endpoint URL and API key in the appropriate authentication fields.

    The endpoint URL is provided for you in Incident Management on the page for your custom integration, under the Configuration Information section.

  6. Save the webhook.

  7. If necessary, configure the third-party service to use the webhook when it generates alerts. Consult the documentation for your third-party service if you need help.

  8. Use the features of your third-party service to test the integration by sending a payload to your Incident Management instance.

Configure the custom integration in Incident Management

  1. Go to your Incident Management instance.

  2. Open the page for your custom integration by going to Integrations > Ingestion Services > Create your own Integration > your-integration-name.

  3. In the Map Your Data section, you can view cached payloads of incoming events sent from your third-party service. Confirm that events are flowing in before moving on to the next step. This may take some time.

  4. If your data is structured in a nested format with multiple events below the top level, you may need to enable batch processing (optional).

    Batch processing lets you define a path to events in your payload when events are nested under one or more levels. If your events are at one level, then it is not necessary to use this option. To learn more about batch processing, read Use batch processing with custom integrations.

  5. In the grid under Map Your Data, map payload fields to required Incident Management target fields. Select the payload field or fields on the left you want to map to each of the required fields on the right. If you choose multiple payload fields, Incident Management will apply the value for the first non-blank field to the target field.

    • For events, map payload fields to source, description, check, and severity. In the severity row, click Map Values to specify the severity mappings.

    • For metrics, map payload fields to metric, data, and source.

  6. Map optional Incident Management fields. Click Add a Mapping to add additional rows if needed. Select a payload field or fields on the left, click the target field entry on the right, and choose a regular or tag field. For events, you can also specify a location field.

    You do not need to map every payload field, and you do not need to map to every optional Incident Management field. You can click the trashcan icons to delete any rows that you do not want to map.

    NOTE: Only 10 fields display at a time. If your payload includes more than 10 fields, some fields are hidden. To map a hidden field, begin typing the name in the Payload Fields box. Select the hidden field when it displays.

  7. Map tags. If there are payload fields you want to include which do not have a direct equivalent in the Incident Management event or metric schemas, map them to custom tags. Click Add a Mapping and select the payload field you want to map to a tag on the left. Click the target field entry on the right, click Add Tag, and provide a name for the tag field.

  8. Keep the default mapping type for each row, or optionally change it by clicking the arrow between the payload and target field entries. For a complete list of mapping types, save options, and instructions on how to use them, read Use mapping types in custom integrations.

  9. Go to the Set Your Deduplication Key section to preview, edit, and test your deduplication key (optional). The deduplication key is used to group similar events into alerts. For more information, read Configure deduplication key.

  10. Go to the top of the page and click Save.

    You have finished configuring your custom integration. The integration will remain in the "Provisioned" status until it processes an event or metric. Once incoming data is successfully processed, the status of the integration will change to "Active."

In this section: