Overview
An integration is a configured connection that sends alert messages from Uptrends to external systems, such as email, Slack, PagerDuty, or a custom webhook.
When a monitor detects an issue, Uptrends uses the integrations linked in your alert definitions to deliver notifications to operators or third-party systems.
Use the Integration API to manage Uptrends default, custom, or third-party integrations in your account.
Use cases
- Retrieve integration details to track alerting and status — list integrations in your account, review configuration, and check integration type, and active status.
- Manage integrations by type:
- Create, update, and delete custom integrations
- Retrieve or delete third-party integrations
- Retrieve default integrations
- Control access for operators and operator groups
Prerequisites
Before using the Integration API, make sure you have:
Integration API endpoints
The Integration API exposes the following endpoints for managing integration information.
Integrations
Use the following endpoints to manage default (SMS, Email, and Phone) and third-party integrations (Slack, PagerDuty, and StatusHub).
| Method | Endpoint | Description |
|---|---|---|
GET |
/Integration |
Returns a list of all integrations in the account. |
DELETE |
/Integration/{integrationGuid} |
Deletes the specified integration. Default integration types, including email, phone, and SMS, cannot be deleted. |
GET |
/Integration/{integrationGuid}/Authorizations |
Returns a list of operators and operator groups that have access permissions to the integration. If no authorizations are set, the response body returns an empty list. |
POST |
/Integration/{integrationGuid}/Authorizations |
Creates authorizations for the specified integration. Granting a permission automatically includes any required dependent permissions. For example, granting the EditIntegration permission also grants UseIntegration. |
DELETE |
/Integration/{integrationGuid}/Authorizations/{authorizationGuid} |
Deletes the specified permission for the integration. |
Custom integrations
Custom integrations are third-party integrations of the GenericWebhook type. You can retrieve their general information, such as the integration ID, name, status, and type, using the GET /Integration endpoint.
To retrieve and manage the complete configuration details of a custom integration, use the following Custom endpoints.
Note
Only the
/Integration/Customendpoint allows creating and updating the integration.
| Method | Endpoint | Description |
|---|---|---|
GET |
/Integration/Custom |
Returns a list of all custom integrations in the account. The response includes the integration type and, for custom integrations, an IntegrationDetailUrl that points to the type-specific detail endpoint. |
POST |
/Integration/Custom |
Creates a new custom integration. |
GET |
/Integration/Custom/{integrationGuid} |
Returns the specified custom integration. |
PUT |
/Integration/Custom/{integrationGuid} |
Updates the specified custom integration. |
DELETE |
/Integration/Custom/{integrationGuid} |
Deletes the specified custom integration. |
For endpoint parameters, request and response schemas, and interactive testing, use the Uptrends Integration API.
API examples
Default and third-party integrations
GET response
Example of a GET /Integration response body:
[
{
"IntegrationGuid": "1a23b4e5-6f78-423f-8a1f-f2a8cc399f4b",
"Name": "Alerting by SMS",
"Type": "Sms",
"IsActive": true,
"DefaultSmsProvider": "SmsProviderInternational",
"DefaultUseNumericSender": false
},
{
"IntegrationGuid": "ab123c45-a28c-47b5-bbc8-645c3b93da59",
"Name": "Statuspage",
"Type": "GenericWebhook",
"IntegrationDetailUrl": "Integration/Custom/ab123c45-d28e-47b5-fgh8-645i3b93da59",
"IsActive": true
},
{
"IntegrationGuid": "12a345b6-d061-405f-9b48-c72f34461218",
"Name": "Alerting by email",
"Type": "Email",
"IsActive": true,
"UseHtmlMail": true,
"UseCustomEmailSubjectConfirmedError": false,
"UseCustomEmailSubjectConfirmedErrorPlural": false,
"UseCustomEmailSubjectReminderConfirmedError": false,
"UseCustomEmailSubjectReminderConfirmedErrorPlural": false,
"UseCustomEmailSubjectOK": false,
"UseCustomEmailSubjectOKPlural": false,
"EmailSubjectConfirmedError": "Uptrends Alert! Monitor: \"{{@monitor.name}}\" is not working properly.",
"EmailSubjectConfirmedErrorPlural": "Uptrends Alert! Multiple Monitors are not working properly: \"{{@monitor.name}}\".",
"EmailSubjectReminderConfirmedError": "Uptrends Reminder! Monitor: \"{{@monitor.name}}\" is still not working properly.",
"EmailSubjectReminderConfirmedErrorPlural": "Uptrends Reminder! Multiple Monitors are still not working properly: \"{{@monitor.name}}\".",
"EmailSubjectOK": "Uptrends Alert! Monitor: \"{{@monitor.name}}\" is OK.",
"EmailSubjectOKPlural": "Uptrends Alert! Multiple Monitors are now OK: \"{{@monitor.name}}\"."
}
]
Example of a GET /Integration/{integrationGuid}/Authorizations response body:
{
"AuthorizationId": "12a348ce-385a-4316-9341-a0a22ff3cbcc",
"AuthorizationType": "UseIntegration",
"OperatorGroupGuid": "1234ab52-168e-4d54-bd1c-9e65226e82cb"
}
Custom integrations
Note
Custom integrations are template-based. The exact JSON structure may differ based on the implementations. The schema shown in this document represents a reference structure, not a strict schema enforced across all integrations.
Call GET /Integration and find integrations where Type is GenericWebhook.
Use the IntegrationDetailUrl value as a reference when calling the GET /Integration/Custom/. You may also call GET /Integration/Custom/{integrationGuid} directly, to retrieve the full configuration.
The following shows an example structure of a GET /Integration/Custom response:
[
{
"IntegrationGuid": "ab123c45-a28c-47b5-bbc8-645c3b93da59",
"Name": "Statuspage",
"IsActive": true,
"Notes": "This integration updates the Statuspage component for Uptrends alert status.",
"HttpStepDefinitions": [
{
"HttpStepDefinitionUsageGuid": "ab1234c5-8427-489d-eda6-1923e17c870e",
"Steps": [
{
"Url": "https://api.example.io/v1/pages/{{PageId}}/components/{{ComponentId}}",
"Method": "PATCH",
"Body": "{\r\n \"component\": {\r\n \"status\": \"{{MapTypeToStatusPageStatus({{@alert.type}})}}\"\r\n }\r\n}",
"BodyType": "Raw",
"MultiPartForm": [],
"RequestHeaders": [
{
"Key": "Content-Type",
"Value": "application/json"
},
{
"Key": "Authorization",
"Value": "OAuth {{ApiKey}}"
}
],
"Variables": [
{
"Source": "ResponseBodyJson",
"Property": "[0].ProductId",
"Name": "ProductId",
"Arguments": []
}
],
"Assertions": [
{
"Source": "ResponseStatusCode",
"Property": "",
"Comparison": "Equal",
"TargetValue": "200"
}
],
"UseFixedClientCertificate": false,
"Authentication": {
"Id": "a123b5b6-3c59-4c9d-9335-587e68f3f58f",
"AuthenticationType": "None",
"UserName": "",
"PasswordSpecified": false
},
"IgnoreCertificateErrors": false,
"Delay": 0,
"StepType": "HttpRequest",
"RetryUntilSuccessful": false,
"MaxAttempts": 2,
"RetryWaitMilliseconds": 1000,
"PreRequestScript": "",
"PostResponseScript": "",
"CalculatedContentType": "",
"AllowedTlsVersions": []
}
],
"UserDefinedFunctions": [
{
"Name": "MapTypeToStatusPageStatus",
"Type": "Mapping",
"Mappings": [
{
"Key": "Ok",
"Value": "operational"
},
{
"Key": "Alert",
"Value": "major_outage"
}
]
}
],
"Usages": [
"Alert",
"Ok"
]
}
],
"IntegrationVariables": [
{
"Name": "ApiKey",
"Value": "a",
"IsValueSetInEscalationLevel": false
},
{
"Name": "PageId",
"Value": "b",
"IsValueSetInEscalationLevel": false
},
{
"Name": "ComponentId",
"Value": "c",
"IsValueSetInEscalationLevel": false
}
]
},
{
"IntegrationGuid": "8f7c9fd0-8473-40f2-88bd-6d9ccbf40434",
"Name": "Opsgenie",
"IsActive": true,
"Notes": "This integration sends alerts to Opsgenie.",
"HttpStepDefinitions": [
{
"HttpStepDefinitionUsageGuid": "1abcdef2-345g-496e-9d65-802686fc1245",
"Steps": [
{
"Url": "https://api.example.com/v2/alerts",
"Method": "POST",
"Body": "{\r\n \"message\": \"[Uptrends] {{@monitor.name}}\",\r\n \"alias\": \"{{@incident.key}}\",\r\n \"description\": \"{{@JsonEncode({{@alert.description}})}}\",\r\n \"details\": {\r\n \"alertGuid\": \"{{@alert.alertGuid}}\",\r\n \"type\": \"{{@alert.type}}\",\r\n \"timestampUtc\": \"{{@alert.timestampUtc}}\",\r\n \"timestamp\": \"{{@alert.timestamp}}\",\r\n \"firstErrorUtc\": \"{{@alert.firstErrorUtc}}\",\r\n \"firstError\": \"{{@alert.firstError}}\",\r\n \"firstErrorCheckUrl\": \"{{@alert.firstErrorCheckUrl}}\",\r\n \"firstErrorCheckId\": \"{{@alert.firstErrorCheckId}}\",\r\n \"serverIpv4\": \"{{@alert.serverIpv4}}\",\r\n \"serverIpv6\": \"{{@alert.serverIpv6}}\",\r\n \"numberOfConsecutiveErrors\": \"{{@alert.numberOfConsecutiveErrors}}\",\r\n \"checkpointName\": \"{{@alert.checkpointName}}\"\r\n },\r\n \"priority\": \"{{Priority}}\"\r\n}",
"BodyType": "Raw",
"MultiPartForm": [],
"RequestHeaders": [
{
"Key": "Content-Type",
"Value": "application/json"
},
{
"Key": "Authorization",
"Value": "GenieKey {{ApiKey}}"
}
],
"Variables": [
{
"Source": "ResponseBodyJson",
"Property": "[0].ProductId",
"Name": "ProductId",
"Arguments": []
}
],
"Assertions": [
{
"Source": "ResponseStatusCode",
"Property": "",
"Comparison": "Equal",
"TargetValue": "200"
}
],
"UseFixedClientCertificate": false,
"Authentication": {
"Id": "12a3b4c5-261c-4e90-a5c0-fa2b11bc54da",
"AuthenticationType": "None",
"UserName": "",
"PasswordSpecified": false
},
"IgnoreCertificateErrors": false,
"Delay": 0,
"StepType": "HttpRequest",
"RetryUntilSuccessful": false,
"MaxAttempts": 2,
"RetryWaitMilliseconds": 1000,
"PreRequestScript": "",
"PostResponseScript": "",
"CalculatedContentType": "",
"AllowedTlsVersions": []
}
],
"UserDefinedFunctions": [
{
"Name": "MapTypeToStatusPageStatus",
"Type": "Mapping",
"Mappings": [
{
"Key": "Ok",
"Value": "operational"
},
{
"Key": "Alert",
"Value": "major_outage"
}
]
}
],
"Usages": [
"Alert",
"Reminder"
]
}
],
"IntegrationVariables": [
{
"Name": "ApiKey",
"Value": "a",
"IsValueSetInEscalationLevel": false
},
{
"Name": "Priority",
"Value": "P1",
"IsValueSetInEscalationLevel": false
}
]
}
]
POST and PUT request
Use the same structure for POST /Integration/Custom and PUT /Integration/Custom/{integrationGuid} request bodies. Omit IntegrationGuid when creating a new integration as this is automatically generated.
You may use the Uptrends web application as a starting point to create a custom integration. Retrieve configuration using GET /Integration/Custom/{integrationGuid}, and update them using the API afterwards.
{
"IntegrationGuid": "1c234567-846d-44b4-8991-b8eedc1c68c9",
"Name": "Uptrends Test API",
"IsActive": true,
"Notes": "This integration implementation contains a predefined (but customizable) JSON-formatted message containing the full range of available alerting parameters. ",
"HttpStepDefinitions": [
{
"HttpStepDefinitionUsageGuid": "ab1c9d38-a4ca-4a5b-926f-62228f7b5a68",
"Steps": [
{
"Url": "https://api-test.example.net/Account",
"Method": "GET",
"BodyType": "Raw",
"MultiPartForm": [
{
"Type": "VaultFile",
"Key": "file",
"Value": "b84daa9c-cdf3-4ba8-90fa-49aa70dc80c0"
}
],
"RequestHeaders": [
{
"Key": "Content-Type",
"Value": "application/json"
}
],
"Variables": [
{
"Source": "ResponseBodyJson",
"Property": "[0].ProductId",
"Name": "ProductId",
"Arguments": []
}
],
"Assertions": [
{
"Source": "ResponseStatusCode",
"Property": "",
"Comparison": "Equal",
"TargetValue": "200"
}
],
"UseFixedClientCertificate": false,
"Authentication": {
"Id": "12342229d-68cf-4328-b90c-ecb3094b9eac",
"AuthenticationType": "Basic",
"UserName": "{{Username}}",
"PasswordSpecified": false
},
"IgnoreCertificateErrors": false,
"Delay": 0,
"StepType": "HttpRequest",
"RetryUntilSuccessful": false,
"MaxAttempts": 2,
"RetryWaitMilliseconds": 1000,
"PreRequestScript": "",
"PostResponseScript": "",
"CalculatedContentType": "application/json",
"AllowedTlsVersions": []
}
],
"UserDefinedFunctions": [
{
"Name": "MapTypeToStatusPageStatus",
"Type": "Mapping",
"Mappings": [
{
"Key": "Ok",
"Value": "operational"
},
{
"Key": "Alert",
"Value": "major_outage"
}
]
}
],
"Usages": [
"Alert",
"Ok",
"Reminder"
]
}
],
"IntegrationVariables": [
{
"Name": "ApiUrl",
"Value": "https://example.site/1ab23bcde",
"IsValueSetInEscalationLevel": false
},
{
"Name": "Password",
"Value": "pass",
"IsValueSetInEscalationLevel": false
},
{
"Name": "Username",
"Value": "uname",
"IsValueSetInEscalationLevel": false
}
]
}
API parameters
| Field name | Description |
|---|---|
integrationGuid |
Path parameter. The GUID of the integration. |
authorizationGuid |
Path parameter. The GUID of the permission associated with the integration. |
General API fields
Integration resources use the following properties in request and response bodies:
| Field name | Description |
|---|---|
IntegrationGuid |
The unique identifier of the integration. Assigned automatically when the integration is created. |
Name |
The name of the integration. |
Type |
The integration type. Examples include
Email, Sms, Phone, and GenericWebhook. |
IsActive |
When true, the integration is active. Otherwise, the integration is inactive and not used in any alert definition. |
IntegrationDetailUrl |
The URL to the type-specific integration detail endpoint, if available. |
Additional fields below may also be available based on the integration type.
Email integration fields
The following fields are available when you customize an email integration:
| Field name | Description |
|---|---|
ExtraEmailAddresses |
Additional email addresses that receive alert notifications as configured in the alert definition escalation level. |
UseHtmlMail |
When true, Uptrends sends alert emails in HTML format, including clickable links and formatting. When false, emails are sent as plain text. |
UseCustomEmailSubjectConfirmedError |
When true, confirmed error email alerts use a custom subject. When false, they use the default email subject. |
UseCustomEmailSubjectConfirmedErrorPlural |
When true, confirmed error email alerts for multiple monitors use a custom subject. When false, they use the default email subject. |
UseCustomEmailSubjectReminderConfirmedError |
When true, email reminders for confirmed errors use a custom subject. When false, they use the default email subject. |
UseCustomEmailSubjectReminderConfirmedErrorPlural |
When true, email reminders for multiple monitors with confirmed errors use a custom subject. When false, they use the default email subject. |
UseCustomEmailSubjectOK |
When true, OK email alerts use a custom subject. When false, they use the default email subject. |
UseCustomEmailSubjectOKPlural |
When true, OK email alerts for multiple monitors use a custom subject. When false, they use the default email subject. |
EmailSubjectConfirmedError |
The custom email subject used for confirmed error alerts. |
EmailSubjectConfirmedErrorPlural |
The custom email subject used for confirmed error alerts for multiple monitors. |
EmailSubjectReminderConfirmedError |
The custom email subject used for reminder alerts for confirmed errors. |
EmailSubjectReminderConfirmedErrorPlural |
The custom email subject used for reminder alerts for confirmed errors for multiple monitors. |
EmailSubjectOK |
The custom email subject used for OK alerts. |
EmailSubjectOKPlural |
The custom email subject used for OK alerts for multiple monitors. |
SMS integration fields
| Field name | Description |
|---|---|
DefaultSmsProvider |
The SMS provider used for sending alert text messages:
|
DefaultUseNumericSender |
When true, Uptrends uses a numeric sender ID. When false, it uses the default textual sender ID (for example, Uptrends). |
Phone integration fields
| Field name | Description |
|---|---|
DefaultOutgoingPhoneNumber |
The outgoing phone number to place alert calls:
For more information, see OutgoingPhoneNumber API. |
PhoneMessageCulture |
The language telephone operator uses when you receive the call. Supported languages are:
|
UseSpeechFriendlyMonitorNames |
When
true, the telephone operator uses the alternate monitor names set in the Main tab of your Monitor Editor in phone calls. For more information, see Speech-friendly monitor names. |
Custom integration fields
Custom integration fields define the configuration for sending alert messages for Error, OK, and Reminder alert types. Each alert type uses HTTP step definitions that control the request and response behavior, including message content and additional workflow steps, such as authentication and user-defined functions.
| Field name | Description |
|---|---|
Notes |
Free-text field for adding internal comments or details about the custom integration. |
HttpStepDefinitions |
Defines the HTTP structure of the custom integration. Key nested fields:
|
IntegrationVariables |
Variables used in the integration for credentials or reusable values. |
Other API fields
API fields specific to specific integrations, including StatusHub and PagerDuty.
| Field name | Description |
|---|---|
IntegrationServices |
Applies to StatusHub integration. List of integration service IDs associated with the integration. |
IntegrationServiceGuid |
The unique identifier of a StatusHub integration service. |
StatusHubServiceList |
Applies to StatusHub integration. List of Status Hub services, including the MonitorGuid and IntegrationServiceGuid. |
UseSilentMode |
Applies to StatusHub integration. When true, the integration only logs the updates in the status page. When false, users receive an alert notification about the updates. |
IntegrationKey |
Applies to PagerDuty integration. The integration key. Only returned when the authenticated user has edit permission on the integration. |
Authorization fields
| Field name | Description |
|---|---|
AuthorizationId |
The unique id of the authorization. |
AuthorizationType |
The permission type associated with the integration. Options include:
|
Troubleshooting
This section covers common HTTP errors and troubleshooting steps for the Integration API.
Common errors
Common HTTP status codes and their descriptions:
| Status Code | Description |
|---|---|
| 200 | OK — request successful. |
| 201 | Created — the resource was created successfully (for example, a custom integration or authorization). |
| 204 | No content — the request completed successfully and no response body was returned. This applies to successful PUT and DELETE requests. |
| 400 | Bad request — invalid request parameters or missing required fields. |
| 401 | Unauthorized — invalid or missing authentication credentials. |
| 403 | Forbidden — one or more validation errors occurred. This may be related to account permissions. |
| 404 | Not Found — the specified authorizationGuid or integrationGuid was not found. |
| 500 | Internal Server Error — a server-side error occurred. |
General troubleshooting guide
Ensure that you:
- Always validate your request data before sending API calls.
- Use appropriate HTTP methods for each operation.
For further assistance, please reach out to our Support team.
Related articles
For more details, refer to the following articles:
- Uptrends Integration API documentation — interactive API documentation with detailed endpoint specifications.
- API changelog — latest API updates and deprecation notices.