Employee events

The following events can be used to create Employee data updates Webhooks.

Working with webhook events

Before you dive into the various event types, make sure to follow these key steps:

  1. Start by exploring our guide Getting started with Bob webhooks.
  2. Important: We strongly recommend not relying solely on the data provided in the webhook payload. Make an API call to retrieve the necessary data in the most accurate way. To learn more, see our best practices.

Basic webhook events

EventTypeDescription
Updatedemployee.updatedTriggered when an employee's field is updated.
Triggered also when an employee's table is updated if it affects the lifecycle.
To learn more, see Table events.
Createdemployee.createdTriggered when an employee is created.
Deletedemployee.deletedTriggered when an employee is deleted.

Tables webhook events

EventTypeDescription
Table Createdtable.entry.createdTriggered when an entry is added to an employee’s table.
Table Updatedtable.entry.updatedTriggered when an entry is updated in an employee’s table.

Notes:

  1. Deleting a table entry will not trigger a webhook event.
  2. Not all tables will trigger the webhook events. To learn more, see How table event are triggered

Lifecycle webhook events

Lifecycle events refer to updates that affect an employee's status. These updates create an entry in the employee's lifecycle table and are triggered automatically when the lifecycle entry becomes effective.
To learn more, see Lifecycle events.

EventTypeDescription
Inactivatedemployee.inactivatedTriggered when an employee is set to be on leave or terminated, once the corresponding lifecycle entry becomes effective.
Activatedemployee.activatedTriggered when an employee's access is enabled, once the corresponding lifecycle entry becomes effective.
Joinedemployee.joinedTriggered when an employee is granted access, once the corresponding lifecycle entry becomes effective.
Terminatedemployee.leftTriggered when an employee is set as terminated or on 'Garden leave', depending on which occurs first, once the corresponding lifecycle entry becomes effective.
On Leaveemployee.temporaryLeaveTriggered when an employee is set to be on temporary leave, once the corresponding lifecycle entry becomes effective.

🚧

Important Note:

Bob's Webhooks use Admin access rights, which means the payload may contain sensitive data and should be managed carefully, especially in the following events:

  • "Employee Update"
  • "Table Entry Created"
  • "Table Entry Updated"

For example, when updating the payroll data, the payroll table update event may send a payload which contains salary data.

How events triggered

How basic events are triggered

Creating an employee, deleting it or updating an employee’s field will trigger the equivalent events.

When updating an employee's field, an ‘employee update’ event will be triggered and the event's payload will contain both the old values and the new values.

Calculate fields
Calculated fields, such as Full Name , are based on other base fields. They will trigger the update event when one of the base fields (First and Last Name) is updated.

How table events are triggered

When adding or updating an entry in an employee table, this action will trigger the following events:

  1. Table entry created or 'table.entry.updated': depending on the operation. Note that deleting an entry does trigger any events.
  2. Employee updated: If you update the 'current' table entry (i.e., the entry with the current effective date), it will also trigger an 'employee.updated' event, as this change impacts the employee's current data.

The following tables do not trigger a 'table updated/created' event:

  • Training
  • Equity
  • Positions
  • Jobs

How lifecycle events are triggered

Lifecycle events refer to changes that affect an employee's access status, such as rehiring, placing or returning from leave, and termination. To learn more, check out the lifecycle status in Bob overview.

Lifecycle changes create an entry in the employee's lifecycle table and take effect based on the entry's effective date. This date determines when the change impacts the employee's status.

Lifecycle changes will trigger the following events:

  1. Table entry created - for the entry created in the Lifecycle table.
  2. Employee updated - will be triggered when the entry is created it it impacts the employee's current lifecycle data (e.g., recentLeaveStartDate).
  3. Lifecycle event (Inactivated, Activated, Joined, Terminated, On Leave) - will be triggered automatically when the lifecycle entry becomes effective as part of Bob flows.

Important: When triggered via the flow, the lifecycle events will be triggered automatically at midnight on the effective date of the lifecycle table entry. For example, if an employee is terminated with an effective date of April 17, the termination event will trigger at midnight on April 18 (according to the site’s timezone).

How to implement the Webhook event listener

Your webhook event listener should perform the following:

  1. Receive the Event Notification:
    The Webhook event sends a notification to your endpoint whenever an Employee event is triggered. The payload includes partial employee data and a header key named get-employee with a ready-to-use endpoint URL containing the relevant employee ID.
  2. Retrieve the complete employee data:
    Use the URL from the get-employee parameter in the header to perform the API call and retrieve the complete data relevant to this employee. See Read company employee fields by employee ID.
    For example:
    If get-employee is https://api.hibob.com/v1/people/3332883914770350878
    the employee ID is the last part: '3332883914770350878'.

Notes

  1. The values that are returned in fields that contain an item selected from a list represent the item ID, and not the item display name. To obtain the corresponding display value, use the HiBob metadata API. To learn more, see Fields and lists metadata.
  2. The provided payloads are only examples; the actual payload will vary based on how your account's data is organized, for example, whether you have custom fields or whether fields have been relocated to a different category.

Webhook events Payloads

Employee Created Payload

{
  "companyId": 636192,
  "employee": {
    "id": "3373576791477190995",
    "companyId": 636192,
    "firstName": "first",
    "surname": "last",
    "email": "normal@company.com",
    "displayName": "first last",
    "site": "London",
    "siteId": 2510067
  },
  "changedBy": {
    "id": "3332883804594373380",
    "companyId": 636192,
    "firstName": "first1",
    "surname": "last1",
    "email": "normal@company.com",
    "displayName": "Jane Doe",
    "site": "London",
    "siteId": 2510067
  },
  "type": "employee.created",
  "data": {
    "displayName": "first last",
    "personal": {
      "shortBirthDate": null,
      "pronouns": null,
      "honorific": null,
      "nationality": []
    },
    "employee": {
      "payrollManager": null,
      "hrbp": null,
      "itAdmin": null,
      "buddy": null,
      "veteranStatus": [],
      "disabilityStatus": null
    },
    "work": {
      "shortStartDate": "05-22",
      "startDate": "2023-05-22",
      "manager": null,
      "workPhone": null,
      "tenureDuration": {
        "periodISO": "P1Y1D",
        "sortFactor": 361,
        "humanize": "1 year and 1 day"
      },
      "custom": {
        "field_1711886937296": null
      },
      "reportsToIdInCompany": null,
      "durationOfEmployment": null,
      "employeeIdInCompany": null,
      "reportsTo": {
        "email": null
      },
      "workMobile": null,
      "indirectReports": null,
      "siteId": 2510067,
      "department": "Creative",
      "tenureDurationYears": 1.002,
      "tenureYears": 1,
      "isManager": false,
      "title": "Chief Architect",
      "site": "London",
      "originalStartDate": "2023-05-22",
      "activeEffectiveDate": "2023-05-22",
      "directReports": null,
      "secondLevelManager": null,
      "yearsOfService": 0,
      "daysOfPreviousService": null
    },
    "companyId": 636192,
    "about": {
      "foodPreferences": [],
      "socialData": {
        "linkedin": null,
        "twitter": null,
        "facebook": null
      },
      "hobbies": [],
      "superpowers": [],
      "about": null,
      "avatar": ""
    },
    "email": "normal@company.com",
    "surname": "last",
    "home": {
      "privateEmail": null
    },
    "id": "3373576791477190995",
    "firstName": "first"
  },
  "previous": null,
  "creationDate": "2023-05-22T12:41:54.634633"
}

Employee Joined Payload

{
  "companyId" : 5079231109090900621,
  "employee" : {
    "id" : "2b2512d0-e0f0-43",
    "companyId" : 5079231109090900621,
    "firstName" : "first",
    "surname" : "last",
    "email" : "normal@company.com",
    "displayName" : "first last",
    "avatar" : "http://images2.onionstatic.com/clickhole/3447/6/original/800.jpg"
  },
  "changedBy" : {
    "id" : "caa00387-69b9-45",
    "companyId" : 5079231109090900621,
    "firstName" : "JuKxl",
    "surname" : "sj5NgKb",
    "email" : "admin@company.com",
    "displayName" : "NF6ZJAHwNSgt",
    "avatar" : null
  },
  "type" : "employee.joined",
  "data" : {
    "id" : "2b2512d0-e0f0-43",
    "firstName" : "first",
    "surname" : "last",
    "email" : "normal@company.com",
    "displayName" : "first last",
    "personal" : {
      "honorific" : null,
      "secondName" : null,
      "gender" : null,
      "shortBirthDate" : null,
      "nationality" : null,
      "communication" : {
        "slackUsername" : null,
        "skypeUsername" : null
      },
      "custom" : { }
    },
    "about" : {
      "avatar" : "http://images2.onionstatic.com/clickhole/3447/6/original/800.jpg",
      "about" : "Something about me",
      "socialData" : { },
      "hobbies" : [ ],
      "superpowers" : [ ],
      "foodPreferences" : [ ],
      "custom" : { }
    },
    "work" : {
      "workPhone" : "04-04040404",
      "workMobile" : "0505050505",
      "employeeIdInCompany" : 12,
      "title" : "Developer",
      "startDate" : "2023-07-05",
      "shortStartDate" : "07-05",
      "lengthOfService" : 0,
      "site" : "New York",
      "department" : "Engineering",
      "reportsTo" : {
        "id" : "manager_id",
        "firstName" : null,
        "surname" : null,
        "email" : null
      },
      "activeEffectiveDate" : null,
      "custom" : { }
    },
    "custom" : {
      "tabName" : { }
    }
  },
  "creationDate" : "2023-07-05T11:06:26.926"
}

Employee Terminated Payload

{
  "companyId" : 8912898557919922434,
  "employee" : {
    "id" : "5272b8b3-3ee3-45",
    "companyId" : 8912898557919922434,
    "firstName" : "first",
    "surname" : "last",
    "email" : "normal@company.com",
    "displayName" : "first last",
    "avatar" : "http://images2.onionstatic.com/clickhole/3447/6/original/800.jpg"
  },
  "changedBy" : {
    "id" : "27fefb03-46da-4b",
    "companyId" : 8912898557919922434,
    "firstName" : "HjNx1",
    "surname" : "Y8vB224",
    "email" : "admin@company.com",
    "displayName" : "EihuD40vfvsn",
    "avatar" : null
  },
  "type" : "employee.left",
  "data" : {
    "id" : "5272b8b3-3ee3-45",
    "firstName" : "first",
    "surname" : "last",
    "email" : "normal@company.com",
    "displayName" : "first last",
    "personal" : {
      "honorific" : null,
      "secondName" : null,
      "gender" : null,
      "shortBirthDate" : null,
      "nationality" : null,
      "communication" : {
        "slackUsername" : null,
        "skypeUsername" : null
      },
      "custom" : { }
    },
    "about" : {
      "avatar" : "http://images2.onionstatic.com/clickhole/3447/6/original/800.jpg",
      "about" : "Something about me",
      "socialData" : { },
      "hobbies" : [ ],
      "superpowers" : [ ],
      "foodPreferences" : [ ],
      "custom" : { }
    },
    "work" : {
      "workPhone" : "04-04040404",
      "workMobile" : "0505050505",
      "employeeIdInCompany" : 12,
      "title" : "Developer",
      "startDate" : "2023-07-05",
      "shortStartDate" : "07-05",
      "lengthOfService" : 0,
      "site" : "New York",
      "department" : "Engineering",
      "reportsTo" : {
        "id" : "manager_id",
        "firstName" : null,
        "surname" : null,
        "email" : null
      },
      "activeEffectiveDate" : null,
      "custom" : { }
    },
    "custom" : {
      "tabName" : { }
    }
  },
  "creationDate" : "2023-07-05T11:10:44.625"
}

Employee Updated Payload

{
  "companyId": 6362192,
  "employee": {
    "id": "3373576791477190995",
    "companyId": 6362192,
    "firstName": "first",
    "surname": "last",
    "email": "normal@company.com",
    "displayName": "first last",
    "site": "London",
    "siteId": 2838510067
  },
  "changedBy": {
    "id": "3332883804594373380",
    "companyId": 636192,
    "firstName": "first1",
    "surname": "last1",
    "email": "normal@company.com",
    "displayName": "first1 last1",
    "site": "London",
    "siteId": 2838510067
  },
  "type": "employee.updated",
  "data": {
    "fieldUpdates": [
      {
        "path": "/work/site",
        "originalValue": null,
        "newValue": "London (Demo)"
      },
      {
        "path": "/work/department",
        "originalValue": null,
        "newValue": "Creative"
      },
      {
        "path": "/work/title",
        "originalValue": null,
        "newValue": "Chief Architect"
      },
      {
        "path": "/work/siteId",
        "originalValue": null,
        "newValue": 2838510067
      },
      {
        "path": "/work/activeEffectiveDate",
        "originalValue": null,
        "newValue": "2023-05-22"
      }
    ]
  },
  "previous": null,
  "creationDate": "20234-05-22T12:41:54.624909"
}{
  "companyId": 6399996192,
  "employee": {
    "id": "3373576791477190995",
    "companyId": 636192,
    "firstName": "first",
    "surname": "last",
    "email": "normal@company.com",
    "displayName": "first last",
    "site": "London (Demo)",
    "siteId": 2838510067
  },
  "changedBy": {
    "id": "3332883804594373380",
    "companyId": 636192,
    "firstName": "first1",
    "surname": "last1",
    "email": "normal@company.com",
    "displayName": "Demo",
    "site": "London",
    "siteId": 2838510067
  },
  "type": "employee.updated",
  "data": {
    "fieldUpdates": [
      {
        "path": "/work/site",
        "originalValue": null,
        "newValue": "London (Demo)"
      },
      {
        "path": "/work/department",
        "originalValue": null,
        "newValue": "Creative"
      },
      {
        "path": "/work/title",
        "originalValue": null,
        "newValue": "Chief Architect"
      },
      {
        "path": "/work/siteId",
        "originalValue": null,
        "newValue": 2510067
      },
      {
        "path": "/work/activeEffectiveDate",
        "originalValue": null,
        "newValue": "2023-05-22"
      }
    ]
  },
  "previous": null,
  "creationDate": "2023-05-22T12:41:54.624909"
}

Employee Deleted Payload

{
  "companyId" : 8989154816019085952,
  "employee" : {
    "id" : "9770835e-365c-4c",
    "companyId" : 8989154816019085952,
    "firstName" : "first",
    "surname" : "last",
    "email" : "normal@company.com",
    "displayName" : "first last",
    "avatar" : "http://images2.onionstatic.com/clickhole/3447/6/original/800.jpg"
  },
  "changedBy" : {
    "id" : "9cce0b76-4dd1-49",
    "companyId" : 8989154816019085952,
    "firstName" : "lpAbC",
    "surname" : "OaHGMLR",
    "email" : "admin@company.com",
    "displayName" : "RhBF5JgW08gU",
    "avatar" : null
  },
  "type" : "employee.deleted",
  "data" : {
    "id" : "9770835e-365c-4c",
    "firstName" : "first",
    "surname" : "last",
    "email" : "normal@company.com",
    "displayName" : "first last",
    "personal" : {
      "honorific" : null,
      "secondName" : null,
      "gender" : null,
      "shortBirthDate" : null,
      "nationality" : null,
      "communication" : {
        "slackUsername" : null,
        "skypeUsername" : null
      },
      "custom" : { }
    },
    "about" : {
      "avatar" : "http://images2.onionstatic.com/clickhole/3447/6/original/800.jpg",
      "about" : "Something about me",
      "socialData" : { },
      "hobbies" : [ ],
      "superpowers" : [ ],
      "foodPreferences" : [ ],
      "custom" : { }
    },
    "work" : {
      "workPhone" : "04-04040404",
      "workMobile" : "0505050505",
      "employeeIdInCompany" : 12,
      "title" : "Developer",
      "startDate" : "2017-07-05",
      "shortStartDate" : "07-05",
      "lengthOfService" : 0,
      "site" : "New York",
      "department" : "Engineering",
      "reportsTo" : {
        "id" : "manager_id",
        "firstName" : null,
        "surname" : null,
        "email" : null
      },
      "activeEffectiveDate" : null,
      "custom" : { }
    },
    "custom" : {
      "tabName" : { }
    }
  },
  "creationDate" : "2023-07-05T10:42:39.496"
}

Table entry payloads

When a table entry is created or updated, the payload of the events will include the relevant data for the entry, based on the table type.

Lifecycle entry

	"type": "table.entry.created",
  "data": {
    "status": "parental leave",
    "employeeStatus": "Inactive",
    "reasonType": "Voluntary - Regrettable",
    "leaveReason": "Resigned - Career/Life change",
    "customColumns": {
      "leaveEndDate": "20234-09-03"
    }

To learn more about the Lifecycle data, see List employee's life-cycle status history.

Work entry

  "type": "table.entry.created",
  "data": {
    "title": "Content marketing manager",
    "department": "Marketing",
    "site": "New York (Demo)",
    "siteId": 2510068,
    "reportsTo": {
      "id": "3332883904477558858",
      "firstName": "Anna",
      "surname": "Gibbons",
      "email": "anna.gibbons_636192@samplebob.com",
      "displayName": "Anna Gibbons"
    },
    "activeEffectiveDate": "20234-09-04",
    "workChangeType": "Manager Change",
    "customColumns": {
      "column_1720616785883": null,
      "column_1720966485336": null
    }
  },

To learn more about the Work data, see List employee's work history.

Employment entry

  "type": "table.entry.created",
  "data": {
    "contract": "Full time",
    "type": null,
    "workingPattern": null,
    "standardWorkingPattern": null,
    "standardWorkingPatternId": null,
    "personalWorkingPatternType": null,
    "siteWorkingPattern": {
      "workingPatternType": "hourly",
      "days": {
        "sunday": 0,
        "tuesday": 8,
        "wednesday": 8,
        "monday": 8,
        "friday": 8,
        "thursday": 8,
        "saturday": 0
      },
      "hoursPerDay": 8,
      "workingPatternId": 4719563
    },
    "calendarName": null,
    "calendarId": null,
    "flsaCode": null,
    "salaryPayType": null,
    "fte": 100,
    "weeklyHours": 40,
    "activeEffectiveDate": "2014-11-13",
    "actualWorkingPattern": {
      "workingPatternType": "hourly",
      "days": {
        "sunday": 0,
        "tuesday": 8,
        "wednesday": 8,
        "monday": 8,
        "friday": 8,
        "thursday": 8,
        "saturday": 0
      },
      "hoursPerDay": 8,
      "workingPatternId": 4719563
    },
    "hoursInDayNotWorked": 8,
    "customColumns": {
      "column_1720616809244": null
    }
  },

To learn more about the Employment data, see List employee's employment history.

Payroll entry (salary)

  "type": "table.entry.created",
  "data": {
    "activeEffectiveDate": "2014-11-13",
    "base": {
      "value": 35000,
      "currency": "USD"
    },
    "payPeriod": "Annual",
    "payFrequency": "Every two weeks",
    "customColumns": {
      "column_1720616843821": null
    }
  },

To learn more about the Payroll data, see List employee's salary history.

Bank Accounts entry

  "type": "table.entry.created",
  "data": {
    "id": 5040980,
    "tableId": "bankAccounts",
    "categoryId": "financial",
    "customColumns": {
      "useForBonus": null,
      "bankName": null,
      "routingNumber": "2222",
      "accountNickname": "Checkings",
      "bankAccountType": "Checking",
      "bicOrSwift": null,
      "amount": 23,
      "allocation": "percent",
      "branchAddress": null,
      "accountNumber": "244232325",
      "iban": null
    }
  },

To learn more about the bank accounts data, see List employee's bank accounts.