Install the Open Integration Manager for REST API

BigPanda's self-service monitoring normalizer and configuration engine Open Integration Manager(OIM) takes BigPanda's Open Integration Hub to new heights, allowing you to quickly and easily set up new integrations for monitoring systems not currently supported out of the box.

Compare supported versions and types or read more about the capabilities in the Open Integration Manager documentation.

When configuring an OIM REST API integration, you can set up the integration with a Standard API call, or through a PowerShell script.

Standard API Call

Create an App Key

Create an app key in BigPanda.

👍

Integration Specific

You'll need a separate app key for each integrated system.

Set up the integration configuration

Switch to the Integration Manager tab above to configure details for the integration. Alternatively, you can test sending an event right now by following the steps below.

The Integration Manager configuration requires one of the following:

• A sample monitoring event payload to determine the possible properties that can be used when configuring an integration.
• If you can’t preview a sample event, you can still send monitoring events to the endpoint provided in Step 4. When you navigate to the Integration Manager, just click on Recent payloads view to configure your integration using these events.

Make a REST Call From Your Monitoring System

Configure the integrated system to call the Alerts API endpoint:

https://integrations.bigpanda.io/api/alerts

The Open Integration Manager offers additional flexibility with authentication parameters. The following syntax can be used for the Token and App Key:

Auth Token: 

• query string: access_token=<Your Org Bearer Token>
• header: Authorization: Bearer <Your Org Bearer Token>
• header:  x-auth-token: <Your Org Bearer Token>

App Key: 

• query string: app_key=<Your App Key>
• header: x-app-key: <Your App Key>
• header: app_key: <Your App Key>
• body: { "app_key": "<Your App Key>" }

Additionally, the JSON payload can contain all or a subset of the following fields:

• status - Status of the alert. One of [ ok, critical, warning, acknowledged ].
• host/service/application - Main object that caused the alert. Can be the associated host or, if a host isn’t relevant, a service or an application. If you want to include more than one of these fields, consider specifying the primary and secondary properties.
• timestamp - (Optional) Time that the alert occurred in unix format (UTC timezone). If the time is not specified, the value defaults to the current time.
• check - (Optional) Secondary object or sub-item that caused the alert (often shown as an incident subtitle in BigPanda).
• description - (Optional) Additional free-form text information about this alert.
• cluster - (Optional) Server cluster or logical host-group from which the alert was sent. This value is used to correlate alerts into high-level incidents.
• Additional attributes - (Optional) Additional information you want to have available in the BigPanda Incident Dashboard. You can add any number of custom JSON attributes with a string value to the payload.

This means that an alert can be sent to BigPanda even if the monitoring tool is not able to include any information in the API call’s header. See the full payloads and endpoints below for some examples:

Example 1: 

You can call this endpoint:

<span class="phrase">https://integrations.bigpanda.io</span>/api/alerts?access_token=<span class="phrase"><Your Org Bearer Token></span>

With the following payload:

{
  "app_key": "<span class="phrase"><Your App Key></span>",
  "status": "critical",
  "host": "production-database-1",
  "timestamp": 1678385775,
  "check": "CPU overloaded",
  "description": "CPU is above upper limit (70%)",
  "cluster": "production-databases",
  "my_unique_attribute": "my_unique_value"
}

Example 2: 

You can call this endpoint:

<span class="phrase">https://integrations.bigpanda.io</span>/api/alerts?access_token=<span class="phrase"><Your Org Bearer Token></span>&app_key=<span class="phrase"><Your App Key></span>

With this payload:

{
  "status": "critical",
  "host": "production-database-1",
  "timestamp": 1678385775,
  "check": "CPU overloaded",
  "description": "CPU is above upper limit (70%)",
  "cluster": "production-databases",
  "my_unique_attribute": "my_unique_value"
}

For information on how to send multiple alerts or configure primary and secondary properties, see the Alerts API documentation.

For more information on available features, see the Open Integration Manager documentation.

Create a Test Alert

To validate that everything is configured correctly, send a test alert by running the following command in Shell:

curl -XPOST -H "Content-Type: application/json" \
-H "Authorization: Bearer <span class="phrase"><Your Org Bearer Token></span>" \
<span class="phrase">https://integrations.bigpanda.io</span>L/api/alerts \
-d '{ "app_key": "<span class="phrase"><Your App Key></span>", "status": "critical", "host": "production-database-1", "check": "CPU overloaded" }'

The alert should now appear in the Incidents Dashboard. Resolve the alert by running:

curl -XPOST -H "Content-Type: application/json" \
-H "Authorization: Bearer <span class="phrase"><Your Org Bearer Token></span>" \
<span class="phrase">https://integrations.bigpanda.io</span>/api/alerts \
-d '{ "app_key": "<span class="phrase"><Your App Key></span>", "status": "ok", "host": "production-database-1", "check": "CPU overloaded" }'

PowerShell Script

Create an App Key

Create an app key in BigPanda.

👍

Integration Specific

You'll need a separate app key for each integrated system.

Send an Alert

To validate that everything is configured correctly, send a test alert by running the following command in PowerShell:

$json = @{ app_key = "<span class="phrase"><Your App Key></span>"; status = "critical"; alert = "Hello from PowerShell"; host = "testing" }
$url = "<span class="phrase">https://integrations.bigpanda.io</span>/api/alerts"
$headers = @{"Authorization" = "Bearer <span class="phrase"><Your Org Bearer Token></span>"}
Invoke-RestMethod $url -Method Post -Headers $headers -Body ($json|ConvertTo-Json) -UseBasicParsing -ContentType "application/json"

The alert should now appear in the Incidents Dashboard. Resolve the alert by running:

$json = @{ app_key = "<span class="phrase"><Your App Key></span>"; status = "ok"; alert = "Hello from PowerShell"; host = "testing" }
$url = "<span class="phrase">https://integrations.bigpanda.io</span>/api/alerts"
$headers = @{"Authorization" = "Bearer <span class="phrase"><Your Org Bearer Token></span>"}
Invoke-RestMethod $url -Method Post -Headers $headers -Body ($json|ConvertTo-Json) -UseBasicParsing -ContentType "application/json"

For information on how to send multiple alerts or configure primary and secondary properties, see the Alerts API documentation.

For more information on available features, see the Open Integration Manager documentation.