Integrations service#

Service for managing integrations with external services.

OpenAPI file: IntegrationsService.json

Endpoints#

Generate Slack webhook link#

GET /scout/v2/integrations/slack-oauth/init-webhook

Generates link to request permissions for Slack bot to join workspaces and use a webhook.

Query parameters

workspace string (RID): The (Nominal) workspace for which the link is valid. If not provided, will use the default workspace for the user’s organization, if the default workspace for the organization is configured.
isGovSlack boolean: If true, the link will be generated for a GovSlack workspace. This is required for GovSlack workspaces.

Response

url string

Request

curl

curl "https://api.gov.nominal.io/api/scout/v2/integrations/slack-oauth/init-webhook" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/scout/v2/integrations/slack-oauth/init-webhook",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/scout/v2/integrations/slack-oauth/init-webhook",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/scout/v2/integrations/slack-oauth/init-webhook",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "url": "<url>"
}

Create Slack webhook#

GET /scout/v2/integrations/slack-oauth/redirect

Creates a new Slack integration. Called internally after Slack authorization.

Query parameters

code string required: Temporary authorization code issued by Slack.
state string required

Response

No content (HTTP 204).

Request

curl

curl "https://api.gov.nominal.io/api/scout/v2/integrations/slack-oauth/redirect?code=<code>&state=<state>" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/scout/v2/integrations/slack-oauth/redirect?code=<code>&state=<state>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()

httpx

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/scout/v2/integrations/slack-oauth/redirect?code=<code>&state=<state>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/scout/v2/integrations/slack-oauth/redirect?code=<code>&state=<state>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()


asyncio.run(main())

Response: 204

No content.

Send secure webhook message#

POST /scout/v2/integrations/internal/secure-webhook/{integrationRid}

Sends a message to a secure webhook integration with HMAC-SHA256 signature. Implements retry logic with exponential backoff based on merged delivery configuration. Request configuration overrides take precedence over integration’s stored configuration.

Path parameters

integrationRid string (RID) required

Body

payload string required

JSON payload to send. Will be signed with HMAC-SHA256 using the integration’s signing key. Validated before signing to ensure well-formed JSON.

customHeaders map of string to string

Optional custom headers to override integration’s stored customHeaders for this request. Must not include blocked headers (Authorization, Cookie, X-API-Key, X-Auth-Token, Proxy-Authorization, X-Nominal-*). Merged with integration headers, request overrides take precedence.

deliveryConfig WebhookDeliveryConfig

Optional delivery configuration to override integration’s stored deliveryConfig for this request. Merged with integration config, request overrides take precedence. Cross-field constraints (e.g., maxRetryInterval >= retryInterval) validated on merged result.

Fields of WebhookDeliveryConfig

defaultRequestTimeoutSeconds integer: Default HTTP request timeout in seconds (server default 10, range 5-120)
defaultMaxRetries integer: Default maximum delivery attempts before failing (server default 3, range 0-10)
defaultRetryIntervalSeconds integer: Default initial interval between retry attempts in seconds (server default 15, range 5-300)
defaultExponentialBackoff boolean: Whether to apply exponential backoff to retry intervals (server default true)
defaultMaxRetryIntervalSeconds integer: Default maximum interval between retries when using exponential backoff in seconds (server default 300, range 5-3600)
defaultDeliveryTimeoutSeconds integer: Default overall delivery timeout in seconds before giving up (server default 600, range 10-86400)

Response

An empty JSON object, {}.

Request

curl

curl -X POST "https://api.gov.nominal.io/api/scout/v2/integrations/internal/secure-webhook/<integration rid>" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "payload": "<payload>"
}'

requests

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v2/integrations/internal/secure-webhook/<integration rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={"payload": "<payload>"},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v2/integrations/internal/secure-webhook/<integration rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={"payload": "<payload>"},
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/scout/v2/integrations/internal/secure-webhook/<integration rid>",
            headers={"Authorization": "Bearer <api key>"},
            json={"payload": "<payload>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{}

Delete integration#

DELETE /scout/v2/integrations/{integrationRid}

Deletes an integration by archiving.

Path parameters

integrationRid string (RID) required

Response

No content (HTTP 204).

Request

curl

curl -X DELETE "https://api.gov.nominal.io/api/scout/v2/integrations/<integration rid>" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.delete(
    "https://api.gov.nominal.io/api/scout/v2/integrations/<integration rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()

httpx

import httpx

response = httpx.delete(
    "https://api.gov.nominal.io/api/scout/v2/integrations/<integration rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.delete(
            "https://api.gov.nominal.io/api/scout/v2/integrations/<integration rid>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()


asyncio.run(main())

Response: 204

No content.

Send message#

POST /scout/v2/integrations/send-message

Sends a string message to the specified integration from a checklist execution.

Body

title string

Optional title for the message. 130 characters max.

message string required

tags array of string

20 tags max, 50 characters max each. Tags are used to filter messages in Opsgenie. For other integrations, tags are ignored.

opsGenieAlias string

Alias to use for the Opsgenie alert deduplication. 512 characters max.

integrationRid string (RID) required

priority Priority

Values of Priority

P0
P1
P2
P3
P4

Response

No content (HTTP 204).

Request

curl

curl -X POST "https://api.gov.nominal.io/api/scout/v2/integrations/send-message" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "message": "<message>",
  "integrationRid": "<integration rid>"
}'

requests

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v2/integrations/send-message",
    headers={"Authorization": "Bearer <api key>"},
    json={"message": "<message>", "integrationRid": "<integration rid>"},
)
response.raise_for_status()

httpx

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v2/integrations/send-message",
    headers={"Authorization": "Bearer <api key>"},
    json={"message": "<message>", "integrationRid": "<integration rid>"},
)
response.raise_for_status()

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/scout/v2/integrations/send-message",
            headers={"Authorization": "Bearer <api key>"},
            json={"message": "<message>", "integrationRid": "<integration rid>"},
        ) as response:
            response.raise_for_status()


asyncio.run(main())

Response: 204

No content.

Rotate secure webhook integration signing key#

POST /scout/v2/integrations/internal/{integrationRid}/rotate-signing-key

Rotates the HMAC signing key for a webhook integration. The old key is immediately invalidated and a new key is generated and returned. This is the only way to retrieve the signing key after initial creation.

Path parameters

integrationRid string (RID) required

Response

signingKey string: New HMAC-SHA256 signing key (256-bit, base64-encoded). The old key is immediately invalidated. Store this securely - update your application configuration with the new key before the next webhook delivery.

Request

curl

curl -X POST "https://api.gov.nominal.io/api/scout/v2/integrations/internal/<integration rid>/rotate-signing-key" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v2/integrations/internal/<integration rid>/rotate-signing-key",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v2/integrations/internal/<integration rid>/rotate-signing-key",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/scout/v2/integrations/internal/<integration rid>/rotate-signing-key",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "signingKey": "<signing key>"
}

Errors#

Errors shows how these errors are sent.

Each error’s errorName is Scout: followed by its name below.

Status	Name	Notes
400	`InvalidDeliveryConfig`
400	`InvalidWebhookHeaders`
400	`InvalidWebhookUrl`
400	`NotImplemented`
400	`SlackIntegrationNotAvailable`
400	`UnsupportedOperationForIntegration`
404	`IntegrationNotFound`
404	`IntegrationTokenNotFound`
404	`IntegrationsNotFound`

Types#

CreateIntegrationDetails#

Set type to the name of one of the other fields, and set only that field.

createSimpleWebhookDetails CreateSimpleWebhookDetails
createOpsgenieIntegrationDetails CreateOpsgenieIntegrationDetails
createTeamsWebhookIntegrationDetails CreateTeamsWebhookIntegrationDetails
createPagerDutyIntegrationDetails CreatePagerDutyIntegrationDetails

CreateOpsgenieIntegrationDetails#

apiKey string required
region OpsgenieRegion required

CreatePagerDutyIntegrationDetails#

routingKey string required

CreateSimpleWebhookDetails#

webhook string required: Webhook URL (must be HTTPS in production)
secret string: Optional secret for HMAC-SHA256 signing (recommended)
contentType WebhookContentType: Content-Type for requests (default: application/json)
timeoutSeconds integer: HTTP request timeout in seconds (default: 30, max: 120)
customHeaders map of string to string: Additional headers to include in all requests. Do not put API keys, tokens, or other secrets in custom headers.

CreateTeamsWebhookIntegrationDetails#

webhook string required

Integration#

Configuration details used to connect to an external service.

rid string (RID) required
name string required
description string
integrationDetails IntegrationDetails required
createdAt string (date-time) required
createdBy string (RID) required
isArchived boolean required

IntegrationDetails#

Set type to the name of one of the other fields, and set only that field.

slackWebhookIntegration SlackWebhookIntegration
opsgenieIntegration OpsgenieIntegration
simpleWebhookIntegration SimpleWebhookIntegration
secureWebhookIntegration SecureWebhookIntegration
teamsWebhookIntegration TeamsWebhookIntegration
pagerDutyIntegration PagerDutyIntegration

OpsgenieIntegration#

region OpsgenieRegion required

OpsgenieRegion#

Opsgenie region for the account linked to the provided API key.

US
EU

PagerDutyIntegration#

An empty JSON object, {}.

Priority#

P0
P1
P2
P3
P4

SecureWebhookIntegration#

Advanced webhook integration with HMAC signing, custom headers, and configurable defaults.

Server-side validation enforces: - URL must use HTTPS protocol - customHeaders blocklist (see customHeaders field documentation)

url string required: Webhook URL (must be HTTPS)
customHeaders map of string to string: Additional HTTP headers to include in all webhook requests. Do not put API keys, tokens, or other secrets in custom headers. Server-side validation rejects security-sensitive headers to prevent credential leakage: Authorization, Cookie, X-API-Key, X-Auth-Token, Proxy-Authorization, and any header starting with X-Nominal-. Validation returns clear error messages for blocked headers.
deliveryConfig WebhookDeliveryConfig required: Retry and timeout configuration for webhook delivery attempts

SimpleWebhookIntegration#

hmacSecretRid string (RID): Optional RID of secret containing HMAC-SHA256 signing key
contentType WebhookContentType: Content-Type for requests (default: application/json)
timeoutSeconds integer: HTTP request timeout in seconds (default: 30, max: 120)
customHeaders map of string to string: Additional headers to include in all requests. Do not put API keys, tokens, or other secrets in custom headers.

SlackInstanceType#

COMMERCIAL
GOV

SlackWebhookIntegration#

teamName string required
channel string required
channelId string required
slackInstance SlackInstanceType

TeamsWebhookIntegration#

An empty JSON object, {}.

UpdateIntegrationDetails#

Set type to the name of one of the other fields, and set only that field.

simpleWebhook UpdateSimpleWebhookDetails
secureWebhookIntegration UpdateSecureWebhookIntegrationDetails
opsgenieIntegration UpdateOpsgenieIntegrationDetails
teamsWebhook UpdateTeamsWebhookIntegrationDetails
pagerDuty UpdatePagerDutyIntegrationDetails

UpdateOpsgenieIntegrationDetails#

apiKey string required
region OpsgenieRegion required

UpdatePagerDutyIntegrationDetails#

routingKey string required

UpdateSecureWebhookIntegrationDetails#

Configuration for updating an advanced webhook integration. This is a full replacement update - all fields must be provided. Optional retry/timeout fields not provided will be reset to server defaults. Note: To rotate the signing key, use the rotateSecureWebhookIntegrationSigningKey endpoint instead.

url string required: Webhook URL (must be HTTPS)
customHeaders map of string to string: Additional HTTP headers to include in all webhook requests. Do not put API keys, tokens, or other secrets in custom headers. Server-side validation rejects security-sensitive headers to prevent credential leakage: Authorization, Cookie, X-API-Key, X-Auth-Token, Proxy-Authorization, and any header starting with X-Nominal-. Validation returns clear error messages for blocked headers.
deliveryConfig WebhookDeliveryConfig required: Retry and timeout configuration for webhook delivery attempts

UpdateSimpleWebhookDetails#

webhook string required: Webhook URL (must be HTTPS in production)
secret string: Optional secret for HMAC-SHA256 signing
contentType WebhookContentType: Content-Type for requests
timeoutSeconds integer: HTTP request timeout in seconds
customHeaders map of string to string: Additional headers to include in all requests. Do not put API keys, tokens, or other secrets in custom headers.

UpdateTeamsWebhookIntegrationDetails#

webhook string required

WebhookContentType#

Content-Type for webhook requests

APPLICATION_JSON: application/json
APPLICATION_X_WWW_FORM_URLENCODED: application/x-www-form-urlencoded

WebhookDeliveryConfig#

Retry parameters serve as integration-level defaults that can be overridden at runtime.

Server-side validation enforces: - defaultRequestTimeoutSeconds maximum of 120 - defaultMaxRetryIntervalSeconds must be >= defaultRetryIntervalSeconds when both are provided

defaultRequestTimeoutSeconds integer: Default HTTP request timeout in seconds (server default 10, range 5-120)
defaultMaxRetries integer: Default maximum delivery attempts before failing (server default 3, range 0-10)
defaultRetryIntervalSeconds integer: Default initial interval between retry attempts in seconds (server default 15, range 5-300)
defaultExponentialBackoff boolean: Whether to apply exponential backoff to retry intervals (server default true)
defaultMaxRetryIntervalSeconds integer: Default maximum interval between retries when using exponential backoff in seconds (server default 300, range 5-3600)
defaultDeliveryTimeoutSeconds integer: Default overall delivery timeout in seconds before giving up (server default 600, range 10-86400)

Page design based on Scalar, MIT License.

Integrations service#

Endpoints#

Generate Slack webhook link#

Create Slack webhook#

Create integration#

Create secure webhook integration#

Send secure webhook message#

Delete integration#

Update integration metadata#

Get integration#

Update integration details#

List integrations#

Send message#

Rotate secure webhook integration signing key#

Errors#

Types#

CreateIntegrationDetails#

CreateOpsgenieIntegrationDetails#

CreatePagerDutyIntegrationDetails#

CreateSimpleWebhookDetails#

CreateTeamsWebhookIntegrationDetails#

Integration#

IntegrationDetails#

OpsgenieIntegration#

OpsgenieRegion#

PagerDutyIntegration#

Priority#

SecureWebhookIntegration#

SimpleWebhookIntegration#

SlackInstanceType#

SlackWebhookIntegration#

TeamsWebhookIntegration#

UpdateIntegrationDetails#

UpdateOpsgenieIntegrationDetails#

UpdatePagerDutyIntegrationDetails#

UpdateSecureWebhookIntegrationDetails#

UpdateSimpleWebhookDetails#

UpdateTeamsWebhookIntegrationDetails#

WebhookContentType#

WebhookDeliveryConfig#