Managing Subscriptions
Use the Subscription Management APIs to manage the delivery of telemetry data to your data collector.
Prerequisites
-
Before calling the Subscription Management APIs, refer to Data Collector Setup to set up a sink type of your choice using Splunk, Slack, PagerDuty, or Datadog.
-
To use Observability APIs, the user must have the
Fabric Stream Subscription Manager
role. -
Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication. Refer to API Authentication for more information on how to authenticate your requests to the Equinix API.
Creating a Subscription
To create a subscription, send a POST
request to the /fabric/v4/streams/<streamId>/subscriptions
endpoint. Specify the Stream ID in the stream
object and your data collector's settings and authentication information in the sink
object in the body of the request.
Refer to the examples below to create a stream subscription for the supported data collectors.
Note: The Subscription API URI/host values only support HTTPS and do not support self-signed certificates.
Splunk
Sample cURL Request:
curl -X 'POST' 'https://api.equinix.com/fabric/v4/streams/<streamId>/subscriptions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Bearer Token>' \
-d '{
"type": "STREAM_SUBSCRIPTION",
"name": "<splunk_subscription_name>",
"description": "<splunk_subscription_desc>",
"sink": {
"uri": "https://http-inputs-<host>.splunkcloud.com:<port>/services/collector/event",
"type": "SPLUNK_HEC",
"settings": {
"eventIndex": "<name_of_eventIndex>",
"metricIndex": "<name_of_metricIndex>",
"source": "<name_of_splunk_hec>"
},
"credential": {
"type": "ACCESS_TOKEN",
"accessToken": "Splunk <Splunk AccessToken>"
}
}
}'
Sample Response:
{
"href": "https://api.equinix.com/fabric/v4/streams/241372e9-79c9-4ef8-b77a-8b8176c228b4/subscriptions/958a9854-dc49-4ded-87bd-be4d0099355e",
"uuid": "958a9854-dc49-4ded-87bd-be4d0099355e",
"type": "STREAM_SUBSCRIPTION",
"name": "eq-splunk ",
"description": "subscription1",
"state": "PROVISIONING",
"enabled": true,
"sink": {
"uri": "https://http-inputs-<host>.splunkcloud.com:<port>/services/collector/event",
"type": "SPLUNK_HEC",
"credential": {
"type": "ACCESS_TOKEN"
},
"batchEnabled": false,
"batchSizeMax": 50,
"batchWaitTimeMax": 5,
"settings": {
"eventIndex": "<name_of_eventIndex>",
"metricIndex": "<name_of_metricIndex>",
"source": "<name_of_splunk_hec>"
}
},
"changelog": {
"createdBy": "user1",
"createdDateTime": "2024-08-12T21:49:21.761029359Z"
}
}
Slack
Sample cURL Request:
curl -X 'POST' 'https://api.equinix.com/fabric/v4/streams/<streamId>/subscriptions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Bearer Token>' \
-d '{
"type": "STREAM_SUBSCRIPTION",
"name": "<slack_subscription_name>",
"description": "<slack_subscription_desc>",
"sink": {
"uri": "<slack_webhook_uri>",
"type": "SLACK"
}
}'
Sample Response:
{
"href": "https://api.equinix.com/fabric/v4/streams/241372e9-79c9-4ef8-b77a-8b8176c228b4/subscriptions/12190e7d-a486-4a77-ba56-fecdab616837",
"uuid": "12190e7d-a486-4a77-ba56-fecdab616837",
"type": "STREAM_SUBSCRIPTION",
"name": "slack_subscription",
"description": "slack_subscription_desc",
"state": "PROVISIONED",
"enabled": true,
"sink": {
"uri": "****",
"type": "SLACK",
"batchEnabled": false,
"batchSizeMax": 50,
"batchWaitTimeMax": 5
},
"changelog": {
"createdBy": "user1",
"createdDateTime": "2024-10-04T13:20:40.127727Z"
}
}
ServiceNow
Sample cURL Request:
curl -X 'POST' 'https://api.equinix.com/fabric/v4/streams/<streamId>/subscriptions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Bearer Token>' \
-d '{
"type": "STREAM_SUBSCRIPTION",
"name": "<servicenow_subscription_name>",
"description": "<servicenow_subscription_desc>",
"sink": {
"host": "https://<host>.service-now.com",
"type": "SERVICENOW",
"settings": {
"source": "<source_name>"
},
"credential": {
"type": "USERNAME_PASSWORD",
"username": "<servicenow-username>",
"password": "<servicenow-password>"
}
}
}'
Sample Response:
{
"href": "https://api.equinix.com/fabric/v4/streams/241372e9-79c9-4ef8-b77a-8b8176c228b4/subscriptions/9b503760-b30f-4eb8-a681-aab1cfa9db1f",
"uuid": "9b503760-b30f-4eb8-a681-aab1cfa9db1f",
"type": "STREAM_SUBSCRIPTION",
"name": "servnow_subscription",
"description": "servnow_subscription_desc",
"state": "PROVISIONING",
"enabled": true,
"sink": {
"host": "https://<host>.service-now.com",
"type": "SERVICENOW",
"credential": {
"type": "USERNAME_PASSWORD"
},
"batchEnabled": false,
"batchSizeMax": 50,
"batchWaitTimeMax": 5,
"settings": {
"source": "source_name",
"metricUri": "https://<host>.service-now.com/api/mid/sa/metrics",
"eventUri": "https://<host>.service-now.com/api/global/em/jsonv2"
}
},
"changelog": {
"createdBy": "user1",
"createdDateTime": "2025-01-22T18:09:20.894582046Z"
}
}
PagerDuty
Sample cURL Request:
curl -X 'POST' 'https://api.equinix.com/fabric/v4/streams/<streamId>/subscriptions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Bearer Token>' \
-d '{
"type": "STREAM_SUBSCRIPTION",
"name": "<pagerduty_subscription_name>",
"description": "<pagerduty_subscription_desc>",
"sink": {
"host": "https://events.pagerduty.com",
"type": "PAGERDUTY",
"credential": {
"type": "INTEGRATION_KEY",
"integrationKey": "<pagerduty_integration_key>"
}
}
}'
Sample Response:
{
"href": "https://api.equinix.com/fabric/v4/streams/241372e9-79c9-4ef8-b77a-8b8176c228b4/subscriptions/dae0726a-87f0-4c5f-8662-ccbcf44a0de2",
"uuid": "dae0726a-87f0-4c5f-8662-ccbcf44a0de2",
"type": "STREAM_SUBSCRIPTION",
"name": "pagerduty-subscription",
"description": "pagerduty-subscription-desc",
"state": "PROVISIONED",
"enabled": true,
"sink": {
"host": "https://events.pagerduty.com",
"type": "PAGERDUTY",
"credential": {
"type": "INTEGRATION_KEY",
"integrationKey": "<encrypted_integration_key>"
},
"batchEnabled": false,
"batchSizeMax": 50,
"batchWaitTimeMax": 5,
"settings": {
"source": "equinix",
"changeUri": "https://events.pagerduty.com/v2/change/enqueue",
"alertUri": "https://events.pagerduty.com/v2/enqueue"
}
},
"changelog": {
"createdBy": "user1",
"createdDateTime": "2024-09-18T22:04:58.664523Z"
}
}
Datadog
Sample cURL Request:
curl -X 'POST' 'https://api.equinix.com/fabric/v4/streams/<streamId>/subscriptions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Bearer Token>' \
-d '{
"type": "STREAM_SUBSCRIPTION",
"name": "<datadog_subscription_name>",
"description": "<datadog_subscription_desc>",
"sink": {
"host": "https://<datadog_host>.datadoghq.com",
"type": "DATADOG",
"credential": {
"type": "API_KEY",
"apiKey": "<datadog_api_key>"
},
"settings": {
"applicationKey": "<datadog_application_key>"
}
}
}'
Sample Response:
{
"href": "https://api.equinix.com/fabric/v4/streams/241372e9-79c9-4ef8-b77a-8b8176c228b4/subscriptions/1a39648d-c407-4470-b08b-454965f31bf4",
"uuid": "1a39648d-c407-4470-b08b-454965f31bf4",
"type": "STREAM_SUBSCRIPTION",
"name": "datadog_subscription",
"description": "datadog_subscription_desc",
"state": "PROVISIONED",
"enabled": true,
"sink": {
"host": "https://<datadog_host>.datadoghq.com",
"type": "DATADOG",
"credential": {
"type": "API_KEY",
"apiKey": "<encrypted_datadog_api_key>"
},
"batchEnabled": false,
"batchSizeMax": 50,
"batchWaitTimeMax": 5,
"settings": {
"metricUri": "https://<datadog_host>.datadoghq.com/api/v2/series",
"eventsUri": "https://<datadog_host>.datadoghq.com/api/v1/events"
}
},
"changelog": {
"createdBy": "user1",
"createdDateTime": "2024-10-07T06:48:45.861755Z",
"updatedDateTime": "2024-10-07T06:48:51.514474Z"
}
}
Microsoft Teams
Sample cURL Request:
curl -X 'POST' 'https://api.equinix.com/fabric/v4/streams/<streamId>/subscriptions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Bearer Token>' \
-d '{
"type": "STREAM_SUBSCRIPTION",
"name": "<ms_teams_subscription>",
"description": "<ms_teams_subscription_desc>",
"sink": {
"uri": "<teams_webhook_uri>",
"type": "TEAMS"
}
}'
Sample Response:
{
"href": "https://api.equinix.com/fabric/v4/streams/241372e9-79c9-4ef8-b77a-8b8176c228b4/subscriptions/12190e7d-a486-4a77-ba56-fecdab616837",
"uuid": "12190e7d-a486-4a77-ba56-fecdab616837",
"type": "STREAM_SUBSCRIPTION",
"name": "ms_teams_subscription",
"description": "ms_teams_subscription_desc",
"state": "PROVISIONED",
"enabled": true,
"sink": {
"uri": "****",
"type": "TEAMS",
"batchEnabled": false,
"batchSizeMax": 50,
"batchWaitTimeMax": 5
},
"changelog": {
"createdBy": "user1",
"createdDateTime": "2024-10-04T13:20:40.127727Z"
}
}
Retrieving a Subscription
To retrieve a subscription's details, send a GET
request to the /fabric/v4/streams/{streamId}/subscriptions/{subscriptionId}
endpoint.
Sample cURL Request:
curl -X 'GET' 'https://api.equinix.com/fabric/v4/streams/241372e9-79c9-4ef8-b77a-8b8176c228b4/subscriptions/557400f8-d360-11e9-bb65-2a2ae2dbcce4' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Bearer Token>'
Sample Response:
{
"href": "https://api.equinix.com/fabric/v4/streams/241372e9-79c9-4ef8-b77a-8b8176c228b4/subscriptions/958a9854-dc49-4ded-87bd-be4d0099355e",
"uuid": "958a9854-dc49-4ded-87bd-be4d0099355e",
"type": "STREAM_SUBSCRIPTION",
"name": "eq-splunk",
"description": "subscription1",
"state": "PROVISIONED",
"enabled": true,
"sink": {
"uri": "https://http-inputs-<host>.splunkcloud.com:<port>/<endpoint>",
"type": "SPLUNK_HEC",
"credential": {
"type": "ACCESS_TOKEN"
},
"settings": {
"eventIndex": "<name_of_eventIndex>",
"metricIndex": "<name_of_metricIndex>",
"source": "<name_of_splunk_hec>"
}
},
"changelog": {
"createdBy": "user1",
"createdDateTime": "2024-08-12T21:49:21.761029Z"
}
}
Deleting a Subscription
To delete a subscription, send a DELETE
request to the /fabric/v4/streams/{streamId}/subscriptions/{subscriptionId}
endpoint.
Sample cURL Request:
curl -X 'DELETE' 'https://api.equinix.com/fabric/v4/streams/241372e9-79c9-4ef8-b77a-8b8176c228b4/subscriptions/557400f8-d360-11e9-bb65-2a2ae2dbcce4' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Bearer Token>'
Sample Response:
{
"href": "https://api.equinix.com/fabric/v4/streams/241372e9-79c9-4ef8-b77a-8b8176c228b4/subscriptions/958a9854-dc49-4ded-87bd-be4d0099355e",
"uuid": "958a9854-dc49-4ded-87bd-be4d0099355e",
"type": "STREAM_SUBSCRIPTION",
"name": "eq-splunk",
"description": "subscription1",
"state": "DEPROVISIONING",
"enabled": true,
"sink": {
"uri": "<protocol>://http-inputs-<host>.splunkcloud.com:<port>/<endpoint>",
"type": "SPLUNK_HEC",
"credential": {
"type": "ACCESS_TOKEN"
},
"settings": {
"eventIndex": "<name_of_eventIndex>",
"metricIndex": "<name_of_metricIndex>",
"source": "<name_of_splunk_hec>"
}
},
"changelog": {
"createdBy": "user1",
"createdDateTime": "2024-08-12T21:49:21.761029Z"
}
}