Add an API Notifier

An API notifier sends a notification via a REST call when a job execution status reaches a specified state (START, SUCCESS, FAILURE, CANCEL) and contains the previously custom defined message, also called a payload.

Prerequisites

You have added a trigger to a released project. For more information on how to add an API trigger, see Add an API Trigger.

Procedure

  1. Choose Control Tower and then the Environments tile.
  2. Choose your environment and then the Triggers view.
  3. Find the trigger for your project, click the and then select Add notifier.
  4. In the Create Notifier screen, select API and click Next.
  5. Open the Notify on dropdown list, and choose the activation event:

    • All status changes: A notification is sent for any status change on the job.

    • Start: A notification is sent when the job starts.

    • Success: A notification is sent when the job is successful.

    • Failure: A notification is sent when the job fails. For more information on available variables for a failure notifier, see Available Variables for Notifiers.

    • Cancel: A notification is sent when the job is canceled.

    • Expired: A notification is sent when the job is failed or expired. A job expired event triggers under two circumstances:

      • When you have a ready job that does not run before the expiration date. This case concerns automations with a scheduled trigger.

      • When you have a job that is running but the timeout is reached, and the agent is not able to send the result due to some unforeseen challenges such as internet connectivity issue. This case concerns automations with an API trigger.

  6. Optional: From the Available variables list, you can use the variables in the Callback URL or Payload field. For more information on available variables, see Available Variables for Notifiers.
  7. Enter a name and a description.
  8. Choose one of the two following options under Target System:

    • Use predefined destinations.

      If you have chosen this option:

      1. Select your Destination from the dropdown list.

        This list shows only destinations that are shared with the environment and have one of the supported authentication types (No Authorization, Basic Authorization or OAuth2 Client Credentials).

      2. Make sure that the base URL of the destination is automatically filled in.

      3. Optional: Specify a path to add to the base URL.

    • Enter credentials.

      If you have chosen this option:

      1. Enter the Callback URL - the target endpoint of the system that you want to notify.

      2. Select the type of Authorization you want to add to the notifier:

        • None: no authorization is passed with the request.

        • Basic: username/password pair is passed with the request.

        • OAuth 2.0: a client ID, client secret, and authorization URL are passed with the request. Enter the following:

          • Auth URL

          • Client ID

          • Client secret

          • Grant type

  9. Select the HTTP Method:

    • GET

    • POST

    • PUT

    • DELETE

  10. Optional: Add a Header to the Notifier: enter the Key and the Value of the Header.
  11. Write the Payload of the Notifier.

    You can enter any JSON payload in an API notifier. As part of your payload definition you can use available variables that you see under the Notifyon dropdown. For example, if you've selected Success event in the Notify on dropdown, you can use ${output} variable in your payload definition. ${output} variable will be resolved at runtime with the output data from the job execution.

    Any Notifier for an API trigger can refer to the ${invocation_context} variable, which contains the invocationContext json object provided in the API trigger payload. This allows calling applications to correlate asynchronous trigger calls with the corresponding notifier callbacks.

    Variable references used in the notifier payload definition are resolved at runtime with the actual data. If there is an invocation context, the data type of the variable references is determined dynamically.