Control Room Webhooks

One of the key features of any integration is the ability to receive events from the platform instead of having to poll the APIs for status updates. We believe webhooks are the simple and efficient technology for achieving this goal.

Webhooks

You can manage your webhooks from your workspace's API section. Registering a webhook is as simple as entering your webhook endpoint address to the webhook configuration dialog. Once you register your webhook, you can view the shared secret used for HMAC calculations (see details for the HMAC calculation below).

Webhooks UI in Control Room

After registration, you will immediately start receiving events for your process and robot run status changes on your webhook endpoint. The events are delivered with POST requests on your endpoint with JSON payloads. Payload formats are documented below.

Payloads

All of the webhook invocations share a common event format, and some events types may specify additional, event-specific attributes. These are documented below.

HMAC signature

To verify that the webhook invocation is coming from Control Room, each event is sent with HMAC signature in the x-rc-signature header. The signature is calculated from the whole request body using SHA-256 hash function and shared secret. You can view the shared secrets from the Control Room UI.

Example for calculating the signature:

// hash calculaction in Node.js when "body" contains the webhook invocation's
// body as a string
const computedSignature = crypto.createHmac('sha256', '<shared-secret>').update(body).digest('hex');

Common event structure

AttributeTypeDescription
idstringUniqued identifier for the reported event. Note: there is a "at least once" guarantee for event delivery which means in some cases the same event may be reported multiple times. You can use this if you need to ensure you only process events once.
webhookEventTimestampstringThe timestamp for webhook invocation.
eventstringThe name of the event that triggered the webhook invocation.
actionstringEvent specific action.

Robot Process Run event structure

These events are specific to a single process run and always have the value process_run in the event attribute. In addition to the standard attributes this event also has following event-specific attributes:

AttributeTypeDescription
actionstringThe action that was performed. May be one of STARTED, COMPLETED
payload.workspaceIdstringThe id of the workspace in which the event happened.
payload.processIdstringThe id of the process in which the event happened.
payload.processRunIdstringThe id of the process run in which the event happened.
payload.statestringThe status of the run. May be one of IP (in-progress), COMPL (completed).
payload.durationintegerPresent when action is COMPLETED. The duration of the run, in seconds.
payload.resultstringPresent when action is COMPLETED. May be one of success, error.
payload.errorCodestringPresent when action is COMPLETED and result is error.

Example

{
  "id": "74921f7b-10bb-4cf0-803a-afbf3cf12bee",
  "webhookEventTimestamp": "2021-01-19T08:49:07.634Z",
  "event": "process_run",
  "action": "STARTED",
  "payload": {
    "workspaceId": "74c54d8b-f523-4ca8-a058-2ab89d576dac",
    "processId": "9244eb52-e05b-4912-ae9b-61acccfb4a5a",
    "processRunId": "d6cb40c7-0d0b-4f44-b7b4-0acec4233875",
    "state": "IP"
  }
}

Robot Run Event structure

These events are specific to a single robot run and always have the value robot_run_event in the event attribute. In addition to the standard attributes this event also has following event-specific attributes:

AttributeTypeDescription
actionstringThe action that was performed. May be one of (in seqNo order): START, BUNDLE_DL_START, BUNDLE_DL_END, BUNDLE_INFO, BUNDLE_UNPACK_START, BUNDLE_UNPACK_END, ENV_SETUP_START, ENV_SETUP_END, EXECUTE_START, EXECUTE_END, ARTIFACT_UL_START, ARTIFACT_UL_END, END.
payload.workspaceIdstringThe id of the workspace in which the event happened.
payload.processIdstringThe id of the process in which the event happened.
payload.processRunIdstringThe id of the process run in which the event happened.
payload.robotRunIdstringThe id of the robot run in which the event happened.
payload.seqNointegerSequence number for the event. Robot runs event have a specific order and each event has a sequence number, starting from 1. This can be used for ordering the events if they are received out-of-order due to request timings etc.
payload.timeStampstringRobot run event's timestamp.
payload.eventTypestringType of the event. Same value as in action.
payload.dataobjectOptional Action specific object with additional information related to the event.

Example

{
  "id": "31071ecf-3e49-4e9a-b5c0-8c6555af3ccd",
  "webhookEventTimestamp": "2021-01-19T08:49:07.526Z",
  "event": "robot_run_event",
  "action": "START",
  "payload": {
    "workspaceId": "74c54d8b-f523-4ca8-a058-2ab89d576dac",
    "processId": "9244eb52-e05b-4912-ae9b-61acccfb4a5a",
    "processRunId": "d6cb40c7-0d0b-4f44-b7b4-0acec4233875",
    "robotRunId": "69f9afd7-c708-42aa-bee5-2166bf29d315",
    "seqNo": 1,
    "data": {
      "workDir": "/home/worker/instance/runs/69f9afd7-c708-42aa-bee5-2166bf29d315"
    },
    "timeStamp": "2021-01-19T08:49:04.463Z",
    "eventType": "START"
  }
}
August 18, 2021