Webhook - Onboarding Integration

Onboarding Integration - Overview

This guide will help you configure the onboarding integration using a Webhook. Once set up, Firstbase will automatically create an employee record when you send a webhook request.

Note: Prior to setting up your integration, please ensure you have admin access and configure your onboarding webhook following these steps.

1. When does the onboarding integration run?

The Onboarding Integration runs immediately when the webhook request is sent. It may take 5-10 mins to see the change reflected in Firstbase.

2. How does the onboarding integration work?

The Onboarding integration will onboard certain users with or without a package based on your configuration settings.

There’s two configuration settings you can add as part of your onboarding integration:

• Package Mapping Rules - Package Mapping Rules allow you to automatically assign a package to a given employee at the time of creation. For example, if you'd want an employee’s in the Marketing department to automatically be assigned a marketing package.
• Customization Options - Customization Options allow you to skip/include only certain employees. For example, if you want to only create employees if their country is SG (Singapore) and their Employment Status is Full-Time.

The following information is used to map data between your Webhook and Firstbase. Some of it is further used if you set up customization logic like automatically assigning packages or skipping certain employees. 

Data Field	Rippling Field Name	Mandatory
firstName	Preferred First Name	YES
lastName	Legal Last Name	YES
workEmail	Employee > Work Email	YES
personalEmail	Employee> Personal Email	YES
countryCode	Home Address > Country	YES
streetAddress	Home Address > Street Address	Only if using Automatic Orders; Should be the address for shipping the equipment
city	Home Address > City	Only if using Automatic Orders; Should be the address for shipping the equipment
postalCode	Home Address > Zip Code	Only if using Automatic Orders; Should be the address for shipping the equipment
region	Home Address > State	Only if using Automatic Orders; Should be the address for shipping the equipment
department	Employee > Department	Only if automating package assignment based on department. See more here.
startDate	Employee > Start Date	YES; The date format needs to be YYYY-MM-DD

 

3. How can I configure the onboarding webhook request?

See instructions here to configure your webhook.

4. How can I customize my integration?

The "Onboarding Integration" can be customized using two steps:

• Create Package Mapping Rules - This step allows you to automatically assign a user to a package when creating them based on some criteria. For example, assign the Marketing package to all my Marketing users.
  • See section here for detailed instructions on how to configure this. 
• Customize your Integration - This step allows you to exclude / include certain employees only when the integration runs.
  • See section here for detailed instructions on how to configure this

4. How can I automatically assign packages when onboarding?

When creating employees, you can follow these steps to automatically assign packages to users:

1. Open up the "Onboard User" flow within your Webhook Integration page 

2. Click on "Edit Package Mappings"

In this step, you can choose how you want to assign packages to each of your employees through the onboarding integration. The following screen will open up:

Click on "Add package mapping rule", which will create a new rule that you can customize with different variables.

In general, you can map packages using the six available operators:

• = Allows for a unique value. 
  • Example: "DEPARTMENT" = "Engineering" 
• ≠ Allows for a unique value.
  • Example: "DEPARTMENT" ≠ "Engineering" 
• IN - Allows for comma separated values. 
  • Example: "DEPARTMENT" IN "Engineering" 
• NOT IN - Allows for comma separated values
  • "Employment Type" NOT IN "Engineering" 
• LIKE - Allows for comma separated values. Useful when you have small different variations for a given field. Like Sales - Contractor; Engineering - Contract; Operations - Contractor...
  
  • Example: "Employment Type" LIKE "Contractor"
• NOT LIKE - Allows for comma separated values. Useful when you have small different variations for a given field. Like Sales - Contractor; Engineering - Contract; Operations - Contractor...
  • Example: "Employment Type" NOT LIKE "Contractor"

All conditions are AND conditions, meaning we'll consider all when assigning a package. There's no OR conditions today.

There's several integration fields you can use when customizing your package mapping using above operators. They include:

Integration Field	Examples
Country	UK, SG  Note: Must follow standard standard 2 character ISO country codes. More info here.
Group Type	This would be "Department"
Group Name	Marketing, Engineering, Product, Operations, etc.
Employment Type	Part-Time, Full-Time
Status	Active, Inactive
Custom 1, 2, 3	We are able to use additional custom fields that you send via the Webhook request in addition to above. However, this needs to be mapped internally. Contact your CSM to learn more.

Let's go through some examples based on possible use cases:

• I'd like to assign a "Product Marketing Package" to all employees in my "Marketing" Department.

For this option, you'll need to configure your package mapping rules the following way: 

• Group Type would = Department
• Group Name would = Marketing
• Package would be set to "Product Marketing"

• I'd like to assign a "Customer Success Package" to all employees in my "Customer Success" Department, that are also based in US and UK. 

For this option, you'll need to configure your package mapping rules the following way: 

• Group Type would = Department
• Group Name would = Customer Success
• Country would be US or UK
• Package would be set to "Customer Success"

Note: When setting up country values please follow standard standard 2 character ISO country codes. More info here -> https://www.iban.com/country-codes.

3. Save your Package Mapping settings

You can add multiple conditions and package mapping rules and once everything is set up, click on "Save changes" and a notification pop up will appear as a confirmation.

 

5. How do I exclude/include certain employees from being onboarded via the onboarding integration?

You can specify within the integration if you only want to create certain employees in Firstbase if they are based in certain countries or if they have a specific employment type, for example. To do so, follow these steps:

1. Open up the "Onboard User" flow within your Webhook Integration page

2. Click on "Edit Configuration"

The following modal will open up. Choose "Add row"

3. Set up your configuration options:

Here, you can choose the fields you want to use to exclude/include only certain employees when the integration runs.

There’s four types of operators available: (1) = and (2) ≠ allow for one field, while (3) IN, (4) NOT IN allow for comma separated fields.

Let's go through some examples:

• I'd like to only create employees based in Singapore and UK

For this option, you'll need to configure your customization settings the following way: 

• Country IN SG, UK

Note: When setting up country values please follow standard standard 2 character ISO country codes. More info here -> https://www.iban.com/country-codes.

• I'd like to only create employees if their employment type is full-time

For this option, you'll need to configure your customization options the following way: 

• Employment Type = Full-Time

Following the same process as mapping rules, you can set up different integration fields, attach an operator, and provide a value to it, you can also add multiple rows for different options.

4. Save your customization options

Once everything is done, click on "Save changes", and a confirmation pop-up will appear. Then click on the “Start” button and we'll automatically onboard all users in your report in Firstbase every day! 🚀

6. I need to use a custom field, how can I approach this?

See FAQ here on using a custom field for your package mapping or customization options.