Event Trigger Subscriptions

A subscription to an event trigger allows the custom application to start receiving trigger invocations from the trigger service.

HTTP

This is the primary subscription type. It involves the trigger service making HTTP request to a custom integration when a trigger is invoked.

Request

POST https://<org>.api.identitynow.com/beta/trigger-subscriptions
  • name (optional): Name of the subscription
  • description (optional): Description of the subscription
  • triggerId (required): Trigger ID
  • type (required): Subscription type (HTTP or INLINE)
  • httpConfig (required if type is HTTP)
  • url (required): URL of the custom application
  • httpDispatchMode (required): Response mode, i.e. SYNC or ASYNC
  • httpAuthenticationType (optional): Authentication type, i.e. NO_AUTH (default), BASIC_AUTH, BEARER_TOKEN
  • basicAuthConfig (optional): Config if BASIC_AUTH is used
    •   `userName` **(required)** if `BASIC_AUTH` is used
      
    •   `password` **(required)** if `BASIC_AUTH` is used
      
  • bearerTokenAuthConfig (optional): Config if BEARER_TOKEN is used
    •   `bearerToken` **(required)** if `BEARER_TOKEN` is used
      
  • inlineConfig (required if type is INLINE)
  • error (optional): Error string indicating failure response from custom integration
  • output (optional): The output from custom integration
  • responseDeadline (optional): Deadline to complete the invocation by, default to PT1H (ISO 8601 duration format)
  • filter (optional): Goessner JsonPath filter expression to set condition for when the trigger should be invoked.
  • enabled (optional): True if subscription should be enabled on create, false otherwise; default to true
{
  "name": "Request-response subscription",
  "description": "Request response from custom-app-url",
  "triggerId": "test:request-response",
  "type": "HTTP",
  "httpConfig": {
    "url": "https://{custom-app-url}",
    "httpDispatchMode": "ASYNC"
  },
  "responseDeadline": "PT1H",
  "filter": "$[?($.identityId == \"201327fda1c44704ac01181e963d463c\")]",
  "enabled": true
}

Response

  • type: Subscription type
  • httpConfig
    • url: URL of the custom application
    • httpAuthenticationType: Authentication type, i.e. NO_AUTH (default), BASIC_AUTH, BEARER_TOKEN
    • basicAuthConfig: Config if BASIC_AUTH is used
    • bearerTokenAuthConfig: Config if BEARER_TOKEN is used
    • httpDispatchMode: Invocation type, i.e. SYNC or ASYNC
  • id: Subscription ID
  • name: Name of the subscription
  • description: Description of the subscription
  • triggerId: Trigger ID
  • responseDeadline: Deadline to complete the invocation by (ISO 8601 duration format)
  • enabled: True if subscription is enabled, false otherwise

201 Created

{
  "type": "HTTP",
  "httpConfig": {
    "url": "https://{custom-app-url}",
    "httpAuthenticationType": "NO_AUTH",
    "basicAuthConfig": null,
    "bearerTokenAuthConfig": null,
    "httpDispatchMode": "ASYNC"
  },
  "id": "1774e567-b486-4245-a4d4-3f256e9bfd9d",
  "name": "Request-response subscription",
  "description": "Request response from custom-app-url",
  "triggerId": "test:request-response",
  "responseDeadline": "PT1H",
  "enabled": true
}

Subscription Limit per Trigger

REQUEST_RESPONSE

There can be only one subscription per REQUEST_RESPONSE trigger. This means that just one custom integration can interact with each REQUEST_RESPONSE trigger at a time.

FIRE_AND_FORGET

There can be at most 50 subscriptions per FIRE_AND_FORGET trigger. This means that at most 50 custom integrations can listen to the same trigger input of a FIRE_AND_FORGET trigger at a time.

Subscription Filter

Subscription filter enables the custom application to conditionally invoke the trigger only when some pre-specified condition is met. Goessner JsonPath filter expression is configured as part of trigger subscription, to only receive trigger input when the expression evaluates to true.

Suppose the trigger service is preparing the following trigger input for trigger invocation:

{
  "identityId": "201327fda1c44704ac01181e963d463c"
}

If the custom application should only receive trigger input when the identityId is “1234”, the filter would be written as follows:

$[?($.identityId == \"1234\")]

Test Subscription

Subscription filter can be tested for correctness beforehand, to ensure that it is valid for use with a trigger input.

Request

POST https://<org>.api.identitynow.com/beta/trigger-subscriptions/validate-filter
  • input (required): Mock trigger input to evaluate filter against
  • filter (required): JsonPath expression

Example filter validation on test:request-response trigger input:

{
  "input": {
    "identityId": "1234"
  },
  "filter": "$[?($.identityId == \"1234\")]"
}

Response

  • isValid: True if filter expression is valid for use against provided input, false otherwise

200 OK

{
  "isValid": true
}

Modifying Existing Subscription

An existing subscription can be modified via a PUT request with the exception of id and triggerId fields.

Example request to modify response deadline of test:request-response subscription:

PUT https://{org}.api.cloud.sailpoint.com/beta/trigger-subscriptions/{subscriptionId}
{
    "triggerId": "test:request-response",
    "type": "HTTP",
    "httpConfig": {
        "url": "https://webhook.site/db18da4e-d9ec-4aae-a423-9fa96a9e9c84",
        "httpDispatchMode": "DYNAMIC"
    },
    "responseDeadline": "PT2H",
    "enabled": true
}

200 OK

{
    "type": "HTTP",
    "enabled": true,
    "id": "ca9d24cb-4d61-4563-88b7-daca9caafecf",
    "triggerId": "test:request-response",
    "responseDeadline": "PT2H",
    "httpConfig": {
        "url": "https://{custom-app-url}",
        "httpAuthenticationType": "NO_AUTH",
        "basicAuthConfig": null,
        "bearerTokenAuthConfig": null,
        "httpDispatchMode": "DYNAMIC"
    }
}

Unsubscribing from a Trigger

A subscription can be deleted via a DELETE request.

DELETE https://{org}.api.cloud.sailpoint.com/beta/trigger-subscriptions/{subscriptionId}

On successful delete, 204 No Content is returned.