# Event Trigger Subscriptions

A custom application that implements a callback URL can subscribe to an event trigger to begin receiving events. A callback URL is simply a RESTful endpoint that accepts a POST request to an endpoint within the application. This callback URL will be provided to the SailPoint event trigger during the subscription process so the trigger know where to send event payloads.

You can subscribe to an event trigger using the REST API endpoint or through the IdentityNow Admin Interface.

# Subscribing to Triggers via the IdentityNow Admin Interface

IMPORTANT: Before configuring a subscription in IdentityNow, make sure you've configured the information the webhook needs to receive event triggers.

Complete the following steps:

  1. Sign in to SailPoint's cloud services and go to the Admin interface, or go to https://{tenant}.identitynow.com/ui/a/admin/event-triggers/triggers

  2. Click Event Triggers. A list of available triggers is displayed.

  3. Click the Subscribe button beside a trigger to subscribe to it. A Fire and Forget type trigger can have up to 50 subscriptions, and a Response Required trigger once.

  4. Enter the following information for your subscription:

    • Subscription Name - Enter a unique name for your subscription.

    • Description - Optionally enter a description for your subscription.

    • Subscription Type - Choose whether your subscription will be an HTTP subscription or an Amazon EventBridge subscription. If you choose HTTP, you will be required to complete the following field:

      • Integration URL - The URL of the webhook.

      If you choose Amazon EventBridge, you will be required to complete the following fields:

      • AWS Region - Your AWS region
      • AWS Account ID - Your AWS Account ID
    • Filter - Optionally, enter a JSON XPath filter expression to specify the conditions under which this trigger should fire.

    • Response Type - For Response Required triggers, specify whether you want the response to be synchronous or asynchronous. You can also choose to allow the integration to provide this information. This is sometimes known as dynamic.

    • Response Deadline - For Response Required triggers using an asynchronous response type, specify how long SailPoint's cloud service should wait for a 200 response before timing out. Use ISO 8601 Duration format. The default Response Deadline is 1 hour. The Response Deadline for synchronous triggers is 10 seconds. This can't be modified.

    • Authentication Type - Choose the type of authentication to use. You may be asked to complete additional fields

      If you choose Bearer Token, you will be required to complete the following field:

      • Bearer Token - The bearer token used for authentication into the integration

      If you choose Basic Auth, you will be required to complete the following fields:

      • User Name - A user name to the integration service
      • Password - The password for the integration service account
    • Enabled/Disabled - Determine whether this subscription is enabled or disabled.

  5. Click Save.

You can take several actions on the Subscriptions page.

Click the slider in the Enabled/Disabled column to change the status of the subscription.

Click the menu icon beside a subscription to do the following:

  • Edit an existing subscription
  • Delete that subscription
  • View the Activity Log for that specific trigger
  • Select Test Subscription to send a test of this trigger using mock data.

Click Activity Log in the left menu to see a complete list of activity for all subscriptions in your org.

# Subscribing via the API

POST https://<tenant>.api.identitynow.com/beta/trigger-subscriptions

Body parameters

  • name (optional): Name of the subscription
  • description (optional): Description of the subscription
  • triggerId (required): Trigger ID
  • type (required): Subscription type: HTTP or INLINE. INLINE is only used for customer POCs.
  • httpConfig (required if type is HTTP)
    • url (required): URL where the custom application will be listening for new events
    • httpDispatchMode (required): Response mode, i.e. SYNC or ASYNC
    • httpAuthenticationType (optional): Authentication type required by the custom application, 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 (opens new window) 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

Example

{
  "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 where the custom application will be listening for new events
    • 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

Example

HTTP Status Code: 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 trigger service to conditionally invoke and send an event to the custom application only when some pre-specified condition is met. Goessner JsonPath filter expression (opens new window) is configured as part of the 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\")]

# Testing a Subscription Filter

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

Request

POST https://<tenant>.api.identitynow.com/beta/trigger-subscriptions/validate-filter

Body

  • 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.

HTTP Status Code: 200 OK

{
  "isValid": true
}

# Modifying Existing Subscriptions

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:

Request

PUT https://{tenant}.api.identitynow.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
}

Response

HTTP Status Code: 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.

Request

DELETE https://{tenant}.api.identitynow.com/beta/trigger-subscriptions/{subscriptionId}

On successful delete, 204 No Content is returned.