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 Moogsoft Cloud.

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 Moogsoft Cloud 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 Moogsoft Cloud 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 Moogsoft Cloud instance.

  • Make sure that you have a valid Moogsoft Cloud 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 Moogsoft Events API or Metrics API schema.

Create a custom integration in Moogsoft Cloud

  1. Within Moogsoft Cloud, navigate to Integrations > Ingestion Services > Create your own Integration.

  2. Click Add New Integration.

  3. Under Moogsoft Endpoint, enter a unique name for your new integration (required).

    Note

    The name of the integration can be anything you choose. Moogsoft Cloud 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 "Moogsoft."

  3. Set the HTTP method to POST.

  4. Paste your Moogsoft Cloud endpoint URL and API key in the appropriate authentication fields.

    Both the endpoint URL and API key are provided for you in Moogsoft Cloud on the page for your custom integration, under the Configuration Information section.

  5. Save the webhook.

  6. 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.

  7. Use the features of your third-party service to test the integration by sending a payload to your Moogsoft Cloud instance.

Configure the custom integration in Moogsoft Cloud

  1. Go to your Moogsoft Cloud 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 Moogsoft 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, Moogsoft 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 Moogsoft 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 Moogsoft field. You can click the trashcan icons to delete any rows that you do not want to map.

  7. Map tags. If there are payload fields you want to include which do not have a direct equivalent in the Moogsoft 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 and is an aggregation of relevant event fields.

    By default, Moogsoft Cloud uses the source, class, service, and check fields to identify events. If you do not map all of these fields, then only the fields in this default set that you have mapped are included in the deduplication key.

    Note

    Customizing deduplication is an advanced feature. Use the recommended fields unless the default deduplication does not meet your needs.

    To learn more about how deduplication works, read Deduplicate events to reduce noise and Events, alerts, and incidents.

  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: