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).
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"
}
}