SignalFx Developers Guide

Working with Integrations

Although SignalFx provides a large number of integrations that you can set up in the web UI, you can also set up integrations using the API. The API supports the following types of integrations:

  • Data retrieval integrations with AWS, Google Cloud Platform, and Microsoft Azure

  • SAML-based authentication integrations

  • Alert notification integrations

To use one of these integrations, you first register it with SignalFx. After that, you configure the integration to communicate between the system you’re using and SignalFx.

Data collection integrations

Data collection integrations connect SignalFx with the monitoring provided by web services. To establish the integration, you do the following:

  1. If necessary, set up the web service to share data with SignalFx.

  2. In the web service interface, find the information that SignalFx uses to authenticate with the service.

  3. Using the SignalFx integrations API, create an integrations object that contains the web service authentication information.

After you complete these steps, SignalFx can retrieve monitoring data from the web service.

To learn more about the SignalFx integrations API for a supported service, see the documentation for the service:

The Integrations API reference documentation describes the request and response bodies for each supported service.

SAML Authentication integrations

SignalFx supports SAML integration with the following SSO systems:

  • Microsoft Active Directory Federation Services (ADFS)

  • Okta

  • OneLogin

  • PingOne

To integrate with a SAML SSO provider:

  1. Create an empty SignalFx integration object using the operation POST https://api.{REALM}.signalfx.com/v2/integration with a request body that specifies the SSO systems you’re using. SignalFx responds with an integration ID it assigns.

  2. Provide the integration ID to your SAML SSO provider. To learn more, see the topic Configuring Single Sign-On in the product documentation.

  3. After you receive authentication credentials from your SSO provider, use the operation PUT https://api.{REALM}.signalfx.com/v2/integration/{INTEGRATION_ID} to update the SAML integration object you created in the first step.

The Integrations API reference documentation describes the request and response bodies for each supported SSO system.

Creating the integration object

The following curl command demonstrates how to create the empty integration object.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
$ curl \
--request POST \
--header 'X-SF-Token: <YOUR_ORG_TOKEN>' \
--header 'content-type: application/json' \

--data \
  '{
    "type": "<SAML_TYPE>",
    "name" : "<INTEGRATION_NAME>"
  }'
https://api.<REALM>.signalfx.com/v2/integration

The response object for a successful request is similar to the following:

1
2
3
4
5
6
{
  type: "<SAML_TYPE>",
  name: "<INTEGRATION_NAME>",
  id: "<INTEGRATION_ID>",
  ...
}

Providing the integration ID to the SSO provider

See the topic Configuring Single Sign-On in the product documentation.

Updating the integration object with the SSO information

Complete the integration using the operation PUT https://api.{REALM}.signalfx.com/v2/integration/<INTEGRATION_ID> with <INTEGRATION_ID> set to the value you received in the response body of the POST request that created the integration.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
$ curl \
--request PUT \
--header 'X-SF-Token: "<YOUR_ORG_TOKEN>"' \
--header 'content-type: application/json' \
--data \
  '{
  	"type": "<SAML_TYPE>",
    "metadata": "<YOUR_METADATA>",
    "certificateName": "<YOUR_CERTIFICATE_NAME>"
  }'
https://api.<REALM>.signalfx.com/v2/integration/<INTEGRATION_ID>

Notification service integrations

Use notification service integrations to add third-party messaging and incident managements services to SignalFx. You can then use these services to send alert messages from detectors.

SignalFx provides support for the following third-party notification services:

  • Amazon EventBridge

  • BigPanda

  • Jira Cloud and Jira Server

  • Microsoft Teams

  • Opsgenie

  • PagerDuty

  • ServiceNow

  • Slack

  • VictorOps

  • Webhook

  • xMatters

SignalFx can also send notifications to third-party services using a Webhook integration.

The request and response bodies for each notification service are described in the Integrations API reference documentation.

Considerations for notification service integrations

Jira integration

The Jira integration supports both Jira Cloud and Jira Server.

To learn more about integrating Jira with SignalFx, see the topic Integrate with Jira in the product documentation.

To learn more about Jira integration using the API, see the topic Integrating with Jira.

ServiceNow integration

To integrate with ServiceNow, you need to create a new user for SignalFx from your ServiceNow service management dashboard. To learn how to do this, and to learn about other fields you for your ServiceNow integration, see the topic Integrate with ServiceNow in the product documentation.

After you create the new user and follow the other instructions, you can create a new ServiceNow integration using the operation POST https://api.{REALM}.signalfx.com/v2/integration.

Webhook integration

Webhook integrations contain headers and authentication information that SignalFx sends in an HTTP request using the integration’s url property. Use a Webhook integration to send notifications using a system for which SignalFx doesn’t provide a specific integration.

When you create a Webhook integration, you specify three properties:

url

URL of the external notification service

headers

Optional associative array (dictionary) of HTTP request header fields. In the POST https://api.{REALM}.signalfx.com/v2/integration request that adds the Webhook integration, specify the dictionary as a JSON object.

SignalFx doesn’t verify the field name or its contents.

sharedSecret

Optional encryption key, as a string. If the property is present and non-null, SignalFx does the following:

  1. Calculates a hash-based message authentication code (HMAC) for the notification message using the HMAC_SHA1 cryptographic hash algorithm and the sharedSecret value as the cryptographic key

  2. Encodes the HMAC in base64

  3. Stores the encoded result in the HTTP header X-SFX-Signature SignalFx adds this header, so you don’t have to specify it in the headers property.

    To verify notification messages in the Webhook target system:

  4. Compute the HMAC_SHA1 code for the incoming HTTP request payload using the same sharedSecret key.

  5. Encode the computed result in base64.

  6. Compare the encoded value to the value of X-SFX-Signature in the incoming HTTP request. If the values match, the message is valid.

© Copyright 2020 Splunk, Inc.

Third-party license information