HiBob
Install the Risotto app from the HiBob Marketplace, then use the HiBob runbook templates for time off and home address requests
Connect HiBob as your HRIS to power employee self-service. Once HiBob is connected:
- The support agent can look up the requester's employee record. Turn this on with Agent access on the People tab of Support agent > Context.
- The HiBob runbook templates handle time off requests and home address lookups. See Set up time off and home address requests.
- HiBob employee events can start automations.
Install from the HiBob Marketplace
Risotto connects to HiBob through the HiBob Marketplace, which handles authentication. Risotto stores the OAuth tokens automatically. You can start the install from Risotto, as below, or from the Risotto app in the HiBob Marketplace.
Start the install from Risotto
Go to Settings > Integrations and click HiBob, in the HRIS category. On the HiBob app card, click Install. Risotto sends you to HiBob.
Approve the install in HiBob
Sign in to HiBob as an admin if prompted, then approve the requested permissions for the Risotto app. HiBob redirects you back to the dashboard once the install is complete.
Confirm the connection
Risotto opens the HiBob integration page. A toast confirms "HiBob connected successfully", and the HiBob app card shows Connected.
Requested permissions
Risotto requests the following HiBob OAuth scopes during install:
| Scope | Purpose |
|---|---|
employee_data:read | Look up employees and retrieve home addresses |
timeoff:read | Read PTO policy types, balances, and existing time off entries |
timeoff:write | Submit time off requests on behalf of the requesting employee |
Set up time off and home address requests
Time off requests and home address lookups use the HiBob runbook templates in Runbooks > Templates. Each template needs HiBob tools, which you create from the template's page.
| Template | What the agent does | Tools it needs |
|---|---|---|
| HiBob Time Off Request | Looks up the requester's balances and submits time off requests in HiBob. Changes to booked time off go to HR. | Get HiBob Time Off Balances, Request HiBob Time Off |
| HiBob Time Off Balance | Looks up the requester's balances. Escalates every request to take, change, or cancel time off to HR. | Get HiBob Time Off Balances |
| HiBob Home Address Lookup | Looks up the requester's home address. Collects a new address and escalates the change to HR. | Get HiBob Home Address |
The two time off templates match the same requests, so turn on only one of them. There is no template that changes a home address, because the HiBob public API cannot write addresses. HiBob time off requests are for full days: when the requester wants part of a day off, the agent escalates to HR instead of submitting.
Find the HiBob templates
Go to Runbooks and click Browse templates. Type
HiBobin Search templates. The HR group lists the HiBob templates.Open a template
Click the template, for example HiBob Time Off Request. The page shows the template's match condition, its agent instructions, the Required tools, and Tips in the side panel.
Create the required tools
Under Required tools, click Create beside each tool that shows Not set up. The tool editor opens for that tool. Keep Restrict to Requestor Only on, so the tool works only on the requester's own record. To have a person review each time off request before it reaches HiBob, turn on Requires Approval on Request HiBob Time Off. Save the tool, and the dashboard returns to the template. If a tool shows Disabled, click Enable.
Use the template
Click Use this template. The button is available once every required tool is ready. If your organization has more than one tool for a required tool, the Choose tool instances dialog asks which one to use: pick one for each and click Continue. The runbook editor opens with the template filled in. Save the runbook and turn it on, as in Create a runbook.
The templates act only for the requester. Before the agent submits time off, it confirms the dates, the time off type, and the amount with the requester and waits for their reply.
Runbook tools
You can also add HiBob tools to your own runbooks. Create them on the Tools page:
| Tool | What it does |
|---|---|
| Get HiBob Employee Information | Reads the employee's profile from HiBob |
| Get HiBob Time Off Balances | Reads the employee's time off balances |
| Request HiBob Time Off | Submits a time off request in HiBob |
| Get HiBob Home Address | Reads the home address on the employee's HiBob record |
- Each tool has a Restrict to Requestor Only option, which is on by default. When it is on, the tool works only for the requester of the ticket.
- Request HiBob Time Off needs the employee's confirmation, given after the agent asks for it. It does not submit a request for a time off type the employee cannot use, or for dates that already have time off.
- No tool can change a home address, because the HiBob public API cannot write addresses. A runbook can read the current address and tell the employee to edit it in Bob.
- If the connection cannot view the Address category in Bob, Get HiBob Home Address replies that no home address was found. Check the permission group of the connection in Bob.
Terminated employees
When HiBob sends the Employee left event for an employee, Risotto marks the employee inactive and stops looking up their HiBob record. The HiBob tools and the employee record lookup then find no record for them.
Automation triggers
HiBob employee events can start a Risotto automation. HiBob sends the events to the Risotto app that you installed from the HiBob Marketplace, so you do not configure a webhook. If the connection is missing or needs a new install, the trigger picker shows the HiBob events as unavailable, with "HiBob is not connected, or needs to be reinstalled."
Triggers
In the trigger picker, open HiBob and choose an event:
| Trigger | HiBob sends it |
|---|---|
| Employee created | Once, when HR adds the employee in HiBob. This is usually before the start date. |
| Employee joined | At midnight on the employee's start date, in the time zone of their site. |
| Employee left | At midnight on the employee's termination date or garden leave start, whichever comes first, in the time zone of their site. |
- Employee joined and Employee left arrive on the effective date, not when HR enters the change in HiBob.
- A rehire sends Employee joined again with the new start date, and the automation runs again.
- If HiBob sends the same event again for the same date, Risotto runs the automation only once.
- If the employee has no valid work email, the automation still runs, with an empty
employee_email. Risotto never uses the personal email.
What the automation receives
| Field | What it holds |
|---|---|
employee_email | The employee's HiBob work email, empty when it is not a valid email address |
employee_name | Their display name, or their first name and surname |
hris_employee_id | Their HiBob employee ID |
event_time | When Risotto received the event |
start_date | Employee created and Employee joined only: the employee's start date in HiBob |
end_date | Employee left only: the employee's termination date in HiBob, which can be after a garden leave start |
Troubleshooting
HiBob does not always fail loudly. With valid credentials but missing grants, a people search comes back empty and a profile comes back with fields removed, while the connection still shows as connected. Risotto names the cause in the tool result and, for the sticky cases, sends one admin alert until the grant is fixed.
Risotto finds no employee, or finds one with only an email
If the connection cannot see any employee at all, Risotto says so: "The HiBob connection is authenticated but cannot see any employees at all." In Bob, add the connection's service user to a permission group whose viewing scope covers employees.
If HiBob returns the employee but the name and other profile fields are missing, Risotto reports that HiBob withheld them. In Bob, grant the connection's permission group view access on the People's data categories (Basic info and Work).
Time off requests fail with a permission error
HiBob accepted the credentials but refused the time off read (HTTP 403). In Bob, grant the connection's permission group view access on the Time Off category.
Risotto says HiBob rejected the connection's credentials
HiBob answered with HTTP 401. An org admin must reconnect HiBob on the HiBob integration page (Settings > Integrations > HiBob).
Disconnecting
To disconnect Risotto from HiBob, click Connected on the HiBob app card of the HiBob integration page, then click Disconnect.... In the Disconnect from HiBob? dialog, click Disconnect. Risotto deletes its stored tokens and opens the HiBob Marketplace in a new tab. Remove the Risotto app there to finish uninstalling it from your workspace.
Something wrong or missing? Report an issue · View as Markdown