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.

Robocorp offers webhooks in several scopes: workspace, process and process run. You can manage your webhooks from your workspace's Integrations section.

General features

To register a webhook, some simple steps should be followed: select the scope of the webhook (workspace or process), enter your webhook endpoint address and optionally configure the events you want to receive. In case you selected process scoped webhook, you also need to select a process from your workspace.

After registering, a webhook can be managed from the webhooks table or going to the webhook view.

Webhook view in Control Room

In the webhook view you can:

  • Update name, endpoint and outgoing events of the webhook
  • View the shared secret used for HMAC signature calculation (see details for the HMAC signature below).
  • Send test events (see event structure below)
  • View webhook logs (see details 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');

Webhook logs

In the webhook view you can see the events that have been sent to your endpoint. In case there was a problem with delivering the event, information regarding the error is shown to help you resolve the issue. Log entries are stored for 2 weeks.

Show data button will show the payload of the event that was sent.

Note: Process run event logs can be examined from the process run timeline view as well.

Test event payload

Variable values are id, webhookEventTimestamp and payload.workspaceId. Otherwise the event content is as in the example below.

{ "id": "35087097-0c00-41d5-bd8b-d034b1fe2969", "webhookEventTimestamp": "2021-08-12T08:53:52.413Z", "event": "test_event", "action": "TEST", "payload": { "workspaceId": "f9b6d52b-110c-430a-a573-774814fbb9e0", "processId": "test", "processRunId": "test", "state": "COMPL", "runNo": 1 } }

Workspace Scoped Webhooks

Workspace scoped webhooks can deliver multiple types of events.

  • Process runs
  • Step runs
  • Robot run events
  • Assistant runs

Payload formats are documented below.

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 the event attribute always has the value set as process_run. 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" } }

Step Run Status Event structure

These events are specific to a single step run and the event attribute always has the value set as step_run_status. 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.stepIdstringThe id of the step in which the event happened.
payload.stepNamestringThe name of the step in which the event happened.
payload.idstringThe id of the step run in which the event happened.
payload.statestringThe state of the step run. May be one of IP (in-progress), COMPL (completed).
payload.stateTsstringThe timestamp of the state of the step run.
payload.startTsstringThe timestamp of when the step run started.
payload.endTsstringPresent when action is COMPLETED. The timestamp of when the step run ended.
payload.durationintegerPresent when action is COMPLETED. The duration of the run, in seconds.
payload.resultstringPresent when action is COMPLETED. May be one OK, ERR, TIMEOUT, TERMINATED, CONNLOSS, START_FAILED

Example

{ "id": "31071ecf-3e49-4e9a-b5c0-8c6555af3ccd", "webhookEventTimestamp": "2022-01-26T09:33:49.526Z", "event": "step_run_status", "action": "COMPLETED", "payload": { "workspaceId": "12cda5a5-2ff6-4a89-854c-b90ad08e1d8c", "processId": "c1d304ce-de38-4896-8c29-816597e28b8c", "processRunId": "89a315a7-010e-8827-b23f-a87c9992ed94", "stepId": "cc3d4468-14c0-40f6-779e-65d11db7d528", "stepName": "Image search", "id": "12115206-a30f-4088-997d-f750e1a6fcea", "state": "COMPL", "stateTs": "2022-01-26T09:33:47.776Z", "startTs": "2022-01-26T09:33:38.982Z", "endTs": "2022-01-26T09:33:47.776Z", "duration": 9, "result": "TERMINATED" } }

Robot Run Event structure

These events are specific to a single robot run and the event attribute always has the value set as robot_run_event. 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" } }

Robot Assistant Run event structure

These events are specific to a single assistant run and the event attribute always has the value set as assistant_run. In addition to the standard attributes this event also has the following specific attributes:

AttributeTypeDescription
actionstringThe action that was performed. May be STARTED or COMPLETED
payload.organizationIdstringThe id of the organization in which the event happened.
payload.workspaceIdstringThe id of the workspace in which the event happened.
payload.assistantIdstringThe id of the assistant in which the event happened.
payload.assitantNamestringThe name of the assistant in which the event happened.
payload.assistantRunIdstringThe id of the assistant run in which the event happened.
payload.runNointegerSpecific run number (run number for each assistant starts from 1)
payload.statestringThe status of the run. May be IP (in-progress) orCOMPL (completed).
payload.createTsstringThe timestamp of when the assistant run was created
payload.stateTsstringThe timestamp of the state of the assistant run.
payload.startTsstringThe timestamp of when the assistant run started.
payload.robot.idstringThe id of the robot that was run.
payload.robot.namestringThe name of the robot that was run.
payload.robot.taskstringThe task of the robot that was run.
payload.startedBy.firstNamestringFirst name of the user who started the assistant run.
payload.startedBy.lastNamestringLast name of the user who started the assistant run.
payload.startedBy.userIdstringUser id of the user who started the assistant run.
payload.startedBy.emailstringEmail of the user who started the assistant run.
payload.startedBy.pictureUrlstringPicture URL of the user who started the assistant run.
payload.endTsstringPresent when action is COMPLETED. The timestamp of when the assistant run ended.
payload.durationintegerPresent when action is COMPLETED. The duration of the run, in seconds.
payload.resultstringPresent when action is COMPLETED. May be one of OK, ERROR, TIMEOUT, TERMINATED.
payload.errorstringPresent when action is COMPLETED and result is ERROR.

Example

{ "id": "18640ce1-e442-4ef7-8663-a2cafbd0041e", "webhookEventTimestamp": "2022-05-24T12:40:19.285Z", "event": "assistant_run", "action": "COMPLETED", "payload": { "organizationId": "211e45c4-4f2a-41bc-bf4a-191b10d68cb5", "workspaceId": "3737e12a-302e-423c-8dcd-3e02db9b8df4", "startedBy": { "firstName": "First Name", "lastName": "Last Name", "userId": "26a27e1d-f19e-46cc-9e8d-28dd27674bfa", "email": "user@robocorp.com", "pictureUrl": "https://lh3.googleusercontent.com/a-/AAuEMRM9KHfP" }, "assistantId": "c92e896b-0701-43d0-a543-58404d26bf31", "assistantName": "assistant name", "assistantRunId": "69502166-5e98-4816-8cbe-a79ce6717047", "duration": 15, "createTs": "2022-05-24T12:40:02.934Z", "startTs": "2022-05-24T12:40:02.934Z", "endTs": "2022-05-24T12:40:17.021Z", "stateTs": "2022-05-24T12:40:17.021Z", "result": "OK", "runNo": 39, "state": "COMPL", "robot": { "id": "203", "name": "New image search", "task": "Image search" } } }

Process Scoped Webhooks

Process scoped webhooks are configured per process. They can deliver only process run events. For convenience, basic management(creation, deletion) of process scoped webhooks can be done also from the process configuration: Process -> Configure -> Notifications -> Webhook Notifications

Process scoped webhooks have a payload structure different from Workspace scoped webhooks. Main differences are the general structure and the inclusion of output work item data. Payload formats are documented below.

Started process run

{ "event": "process_run.started", "id": "123", "state": "started", "workspace": { "id": "456" }, "process": { "id": "789" } }

Completed process run

{ "event": "process_run.completed", "id": "123", "state": "completed", "workspace": { "id": "456" }, "process": { "id": "789" }, "outputs": { "data": [ { "id": "101", "process": { "id": "789" }, "created_at": "2024-01-11T01:01:01.000Z", "payload": { "key": "value" }, "files": [ { "id": "102", "name": "filename.txt", "size": 123, "url": "https://url.to.file", "url_expires_at": "2024-01-12T01:01:01.000Z" } ] } ], "has_more": true }, "work_items_summary": { "failed": 0, "done": 1, "output": 1 } }

Unresolved process run

{ "event": "process_run.unresolved", "id": "123", "state": "unresolved", "workspace": { "id": "456" }, "process": { "id": "789" }, "outputs": { "data": [ { "id": "101", "process": { "id": "789" }, "created_at": "2024-01-11T01:01:01.000Z", "payload": { "key": "value" }, "files": [ { "id": "102", "name": "filename.txt", "size": 123, "url": "https://url.to.file", "url_expires_at": "2024-01-12T01:01:01.000Z" } ] } ], "has_more": true }, "work_items_summary": { "failed": 1, "done": 1, "output": 1 } }

Process Run Scoped Webhooks

Process run scoped webhook is a special type of webhook that is only used for a singular process run. They are not visible in the Integrations section and can only be created when starting a process run via the Start process with provided configuration (/workspaces/{workspaceId}/processes/{processId}/run-request) endpoint of the Robocorp Process API. In this use case three extra payload parameters need to be defined: callbackUrl, secret and eventsToSend.

Example request payload:

{ "type": "default", "callbackUrl": "https://your.callback.url", "secret": "your-callback-secret", "eventsToSend": ["process_run.completed"] }

After the process run has completed, the webhook is removed. Logs are still collected and can be examined from the process run timeline view.

Event Payloads

Process run scoped payloads are identical to Process scoped payload (see above).

Last edit: May 9, 2023