Docs

Integrations / HR systems

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:

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.

  1. 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.

  2. 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.

  3. 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:

ScopePurpose
employee_data:readLook up employees and retrieve home addresses
timeoff:readRead PTO policy types, balances, and existing time off entries
timeoff:writeSubmit 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.

TemplateWhat the agent doesTools it needs
HiBob Time Off RequestLooks 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 BalanceLooks 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 LookupLooks 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.

  1. Find the HiBob templates

    Go to Runbooks and click Browse templates. Type HiBob in Search templates. The HR group lists the HiBob templates.

  2. 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.

  3. 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.

  4. 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:

ToolWhat it does
Get HiBob Employee InformationReads the employee's profile from HiBob
Get HiBob Time Off BalancesReads the employee's time off balances
Request HiBob Time OffSubmits a time off request in HiBob
Get HiBob Home AddressReads 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:

TriggerHiBob sends it
Employee createdOnce, when HR adds the employee in HiBob. This is usually before the start date.
Employee joinedAt midnight on the employee's start date, in the time zone of their site.
Employee leftAt 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

FieldWhat it holds
employee_emailThe employee's HiBob work email, empty when it is not a valid email address
employee_nameTheir display name, or their first name and surname
hris_employee_idTheir HiBob employee ID
event_timeWhen Risotto received the event
start_dateEmployee created and Employee joined only: the employee's start date in HiBob
end_dateEmployee 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