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

Attribute	Type	Description
`id`	`string`	Uniqued 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.
`webhookEventTimestamp`	`string`	The timestamp for webhook invocation.
`event`	`string`	The name of the event that triggered the webhook invocation.
`action`	`string`	Event 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:

Attribute	Type	Description
`action`	`string`	The action that was performed. May be one of `STARTED`, `COMPLETED`
`payload.workspaceId`	`string`	The id of the workspace in which the event happened.
`payload.processId`	`string`	The id of the process in which the event happened.
`payload.processRunId`	`string`	The id of the process run in which the event happened.
`payload.state`	`string`	The status of the run. May be one of `IP` (in-progress), `COMPL` (completed).
`payload.duration`	`integer`	Present when `action` is `COMPLETED`. The duration of the run, in seconds.
`payload.result`	`string`	Present when `action` is `COMPLETED`. May be one of `success`, `error`.
`payload.errorCode`	`string`	Present 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:

Attribute	Type	Description
`action`	`string`	The 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.workspaceId`	`string`	The id of the workspace in which the event happened.
`payload.processId`	`string`	The id of the process in which the event happened.
`payload.processRunId`	`string`	The id of the process run in which the event happened.
`payload.robotRunId`	`string`	The id of the robot run in which the event happened.
`payload.seqNo`	`integer`	Sequence 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.timeStamp`	`string`	Robot run event's timestamp.
`payload.eventType`	`string`	Type of the event. Same value as in `action`.
`payload.data`	`object`	Optional 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