Using callback URLs

Callbacks are functions that are executed after a specific task, often used in programming for asynchronous events. In the context of IBM RPA bots, callback URLs are designated web addresses where the bot communicates, sending notifications to ensure seamless integration and real-time responsiveness.

Callback URLs play a pivotal role in IBM RPA bots, acting as virtual communication channels. These URLs serve as designated endpoints where the bot can send notifications or responses, enabling seamless integration and interaction between the bot and external systems.

One integration is with IBM watsonx Orchestrate, where you can import your automations as skills. From there, users can access and run automations in a no-code user interface. For more information, see IBM Robotic Process Automation in the IBM watsonx Orchestrate documentation.

Before you begin

  • You must have a callback server that is listening on the endpoint that you set. The IBM Robotic Process Automation server sends a POST HTTP request to the endpoint set on the callback URL after the bot finishes.
    • The callback server that exposes the endpoint for the callback URL must be certified with a certificate signed by a Cerficate Authority (CA). See Ordering a CA-signed certificate to understand how to order a CA-signed certificate.
  • You must add the URL to the allowlist. See Adding the URL to the IBM RPA allowlist.
  • You can only use callback URLs when running bots through the API. See Bots APIs.

Adding the URL to the IBM RPA allowlist

  1. Log in to IBM RPA Control Center.
  2. Click Tenants.
  3. On the Tenant Configuration tab, click Security Settings.
  4. Click Add Entry.
  5. Add a domain or IP address to the allowlist.

Procedure

To use a callback URL when running a bot, you must set the callbackUrl header when using the endpoints from the Bots APIs to run bots.

After the bot finishes its run, the IBM RPA server sends the following HTTP request to the callback URL that you set:

POST <CALLBACK_URL_ENDPOINT> HTTP/1.1
Host: <CALLBACK_URL_HOST>
Content-Length: <calculated_during_request>
Content-Type: application/json; charset=utf-8
Expect: 100-continue
X-Forwarded-For: <calculated_during_request>
X-Forwarded-Proto: https
Accept-Encoding: gzip

{
  "jobId": "<JOB_ID>"
  "input": <JSON_INPUT_VARIABLES>
  "output": <JSON_OUTPUT_VARIABLES>,
  "runtimeException": {
      "code": <null | initializationException | runtimeException>
      "message": <ERROR_STRING>
  }
}

Where:

  • <JOB_ID>

    The identifier of the bot run.

  • <JSON_INPUT_VARIABLES>

    A JSON containing the input variables of the bot's script with their loaded values. It contains the value Null if the script does not have any input variables. For more information about input variables, see Creating variables using Designer mode.

    For example, if you run a bot that has the output variable name, and, when the bot finishes running, the value stored in name is Doe, the JSON return on input would be:

    {"name": "Doe"}

  • <JSON_OUTPUT_VARIABLES>

    A JSON containing the output variables of the bot's script with their loaded values. It contains the value Null if the script does not have any output variables. For more information about output variables, see Creating variables using Designer mode.

    For example, if you run a bot that has the output variable name, and, when the bot finishes running, the value stored in name is Doe, the JSON return on output would be:

    {"name": "Doe"}

    Starting from version 23.0.17, your callback server must expect that output variables of the bot always start with lowercase letters.

  • <initializationException | runtimeException>

    The type of error if the bot failed. The error code: null if no error; initializationException if the bot couldn't start or runtimeException if the bot started but failed during runtime.

  • <ERROR_STRING>

    The error message if the bot failed.

Fail policy

Starting from version 23.0.2, when the IBM RPA server sends a request to the callback server, if the callback server responds with one of the HTTP 4xx code or if the certificate validation fails — because either the callback URL endpoint's certificate is self-signed or the endpoint does not have a certificate —, the IBM RPA server does not retry the callback call. Otherwise, the IBM RPA server falls back to the 23.0.0 and 23.0.1 retry rules.

For versions 23.0.0 and 23.0.1, the IBM RPA server retries the callback call complying with the following rules:

  1. Tries twice with a 1-minute interval.
  2. If the previous rule failed, tries 5 times with a 2-minute interval.
  3. If the previous rule failed, tries 3 times with a 10-minute interval.
  4. If the previous rule failed, tries 5 times with a 30-minute interval.
  5. If the previous rule failed, tries each hour for 2 days.
  6. If the previous rule failed, stops trying.