Create your own integration

A custom integration is a user-defined endpoint that ingests JSON objects and converts them to Moogsoft events or metrics. Custom integrations enable you to ingest data from third-party systems with different schemas. When you set up a custom integration, you specify how to map the third-party data to Moogsoft-compatible event or event objects.

Custom integrations have the following features:

  • A UI that guides you through the process of creating a custom endpoint and mapping third-party data fields to Moogsoft fields.

    For events, you can also map third-party severities to Moogsoft severities.

  • Support for basic and bearer token authentication using API keys.

  • No limit on the number of unique API endpoints you can create per workspace.

  • Support for testing and validating the mapping.

    You must validate an integration before you enable it. To be considered valid, an API must include mappings for all required event or metric fields. If the incoming payload does not include the data for a required field, you can specify a plain-text placeholder such as "unknown" instead.

  • If your third-party schema does not include a field that corresponds directly to a Moogsoft field, you can create event workflows to enrich and process your data after ingestion. The custom integration example and the event enrichment example together illustrate a simple end-to-end workflow.

The following video introduces the basic process for creating a custom integration.

Create your own integration example: How it works

This example illustrates how to create a custom API that ingests raw events from an third-party service and automatically converts the data to Moogsoft-compatible events.

You're a DevOps engineer responsible for setting up Moogsoft. Your team uses an open-source tool called mooMON to monitor your infrastructure and applications. You have mooMON set up to post API notifications whenever an event of operational significance occurs.

This example is part of an overall end-to-end workflow for setting up Moogsoft:

  1. In this example, you set up a custom ingestion to ingest your events.

  2. Then you create an events workflow that formats your events into useful alerts.

  3. Finally, you set up a correlation to cluster the resulting alerts into useful incidents.

Compare schemas

Moogsoft uses two different schemas, one for events and one for metrics, to store and process incoming data. To ingest your data, you need to map the mooMon data fields to their equivalents in the Moogsoft events schema.

Moogsoft events schema (required fields)

    "description": "CPU spike to 75%",
    "severity": 4,
    "source": "",
    "check": "cpu",
    "service": [

You review the Moogsoft events API. You note that the fields shown above are required. You need to identify which Moogsoft fields have mooMON equivalents and which fields do not. Comparing the two schemas, you notice the following:

  • The source and service fields do not have mooMON equivalents. This is not a problem: you can put in placeholders for now. Later, you can create an automated workflow to enrich the mooMON events after they get ingested.

  • The mooMON schema includes a metadata field with a lot of useful information. This field doesn't have a Moogsoft equivalent. You can map this to a tag when you set up your custom integration.

Table 4. Moogsoft and mooMON field mapping


mooMON fields







No equivalent. The event source is embedded in the mooMON metadata field, for example:

["ip=,, id=125989934839832182"]




No equivalent. The mooMON schema does not include the service associated with the event.

Create and configure a new endpoint

You know how you want to map your mooMON fields to the Moogsoft Events API. You're now ready to create your custom integration. You log in to the Moogsoft UI and do the following:

  1. Choose Data Config > Integrations > Create your own Integration,, then click Add New Integration .

  2. In Configuration Information, specify the following:

    • Endpoint = moomon-events

    • API Description = mooMON Events API

    • Data Type = Events

  3. Click Save. The setup window for your custom integration appears.

Send your mooMON events to the new endpoint

Now you have an endpoint for your custom integration. You update your mooMON service to send data to the custom endpoint.

At this point the endpoint can ingest any POST notification that has a valid JSON payload and the correct API key.

Map your mooMon data fields to Moogsoft

Now that you have events coming into your new endpoint, you return to the Moogsoft. In the Map your Data section, you do the following:

  1. Select a payload in the Payload View table. the selected payload appears in the pane below.


    NOTE: If your payloads include multiple events in a list under a top-level object, see Batch processing example for data field mapping instructions.

  2. In the Field Mapping table, you map your fields as follows:

    • For mooMON fields with a one-to-one mapping, map the fields to their Moogsoft equivalents as shown in in Table 4, “Moogsoft and mooMON field mapping above.

    • For the Moogsoft fields source and service, which have no mooMON equivalents, simply enter the string TBD.

      These strings will act as placeholders until you create a workflow that populates these fields with the correct values.

    • Map the metadata field, which has no Moogsoft equivalent, to tags.labels.

  3. In addition to mapping fields, you also need to map the mooMon event severities to their Moogsoft equivalents. You click Map Values and map the severities:

  4. You return to the setup page for your custom integration, scroll down to the bottom, and click Save and Enable.

    You can also customize how your integration deduplicates events into alerts,, but this is an advanced feature and you accept the default settings.

  5. You return to the Custom APIs window. The table shows that your custom API is now active.

  6. You go to the Alerts page and see that your mooMon events are now getting converted to alerts.

    There is still one issue: your alerts all have "TBD" as the source and the service.This is not a problem, because the hostnames are contained in the metadata tag. You can create an enrichment workflow to populate these fields. See Event Enrichment Example: How it Works.

Batch processing example

If your payloads include multiple events sent in a "batch" under a single object, then you can identify the top-level object and map the event fields for individual events.

In this example payload, two events are included inside an object called events and an object called key:

    "events": {
        "key": [
                "name": "test1",
                "data": 11,
                "source": "",
                "key": "network",
                "tags": {
                    "origin": "db"
                "utc_offset": "GMT-08:00"
                "name": "test2",
                "data": 11,
                "source": "",
                "key": "network",
                "tags": {
                    "origin": "web"
                "utc_offset": "GMT-08:00"
    "other": "value"

To map the event fields, do the following:

  1. Configure your integration as shown at the top of this procedure. Prior to creating your mappings in step 2 under Map your mooMon data fields to Moogsoft, click Enable Batch Processing.

  2. Click Root Element and select the path to the events in your payloads.

    This option configures the root path for your events. In this example, it is events.key because that is the name of the object path which holds the list of events.

  3. Finish mapping your source fields.

Note that with batch processing enabled and a root element selected, the fields repeated between multiple events are listed once. If there is no defined root element, each field in each event is presented separately for mapping.

With root element selected

Without root element selected

The fields repeated between multiple events are listed once:

Each field in each event is presented separately for mapping:


When you select a root element, other top-level objects are available for mapping at the same level as the root.

In this example, other is at the same level as the root element events.key. The other object could be a field that is included with each event.