Webhook

Note

Webhooks access is currently available on a Platinum subscription and above. If this piques your interest, kindly refer to this article on how you can upgrade your subscription here or reach out to us via live chat on the HR platform

Registering a Webhook

Webhook Properties

To register a webhook, visit the My Webhooks page in the Developer Portal then click the Add Webhooks button. The webhook has 3 required fields:

Create Webhook Modal

Field	Description
Name	Name of webhook.
URL	The URL for the webhook event callback. Please note that for security purposes, we request that you provide HTTPS URIs.
Events	The events that will trigger this particular webhook.

Note

Once a webhook has been set up, you can update your webhook properties through the webhook details page. The new webhook will become active immediately.

Webhook Events

Webhook events that are currently available are:

Employee Created
Employee Onboarded
Employee Updated
Employee Offboarding
Time Off Request Created
Time Off Request Updated
Time Off Request Approved
Time Off Request Declined
Time Off Request Deleted
Employee Bank Account Created
Employee Bank Account Updated
Employee Bank Account Deleted
Employment History Created
Employment History Updated
Employment History Deleted
Timesheet Entry Created
Timesheet Entry Updated
Timesheet Entry Deleted
Certification Created
Certification Updated
Certification Deleted
Certification Archived
Member Certification Created
Member Certification Updated
Member Certification Approved
Member Certification Declined
Member Certification Expired
Member Certification Archived
Member Certification Deleted
Custom Form Response Submitted
Custom Form Response Partially Approved
Custom Form Response Approved
Custom Form Response Declined
Key Result Created
Key Result Updated
Key Result Deleted
Goal Created
Goal Updated
Goal Deleted

Webhook Callback

When an event occurs, it will trigger an HTTP request to the URL configured for the webhook. If the callback URL does not respond with a successful result (i.e. HTTP 200), it will be retried for a maximum of 3 times. If the callback URL still responds unsuccessfully, the webhook event will be marked as failed.

Schema

eventstring

The type of webhook event

dataobject

The payload of webhook event

Callback Body

{  "data": {    "id": "1c8a8e41-82c8-4311-8115-07994dd28ac2",    "approved": true,    "end_date": "2020-02-04",    "start_date": "2020-02-04",    "employee_id": "ba967883-a3db-44a0-b807-bfac746599f7"  },  "event": "leave_request_approved"}

To see the history of webhook events, visit the Webhook History page or Webhook > Event History on the navigation bar from the Developer Portal.

Verify Webhook Request

To ensure the authenticity and integrity of webhook requests from Employment Hero, you must verify the request signature. This confirms that the request is genuinely from Employment Hero and hasn't been tampered with.

Each webhook request from Employment Hero includes two headers:

Header	Description
X-EmploymentHero-Signature	The SHA256 hash signature of the request.
X-EmploymentHero-Timestamp	The timestamp of the request.

The signature is generated using a hash-based message authentication code (HMAC) with SHA-256, which signs the combination of the request payload and the timestamp.

How to Verify the Signature

Get Your Secret Key

Your secret key is available on the webhook configuration page in the Developer Portal. Use this key to generate the hash and verify the request.

Get Webhook Secret

Extract Headers and Payload

Retrieve the X-EmploymentHero-Signature header from the request.
Retrieve the X-EmploymentHero-Timestamp header from the request.
Get the raw JSON payload of the request.

Concatenate Timestamp and Payload

Combine the timestamp and the payload with a dot (.) separator: data = "#{timestamp}.#{json_payload}"

Generate HMAC SHA256 Hash

Use your secret key to generate the SHA256 HMAC hash of the concatenated string.

Compare Signatures

Compare the generated hash with the value in X-EmploymentHero-Signature.
If they match, the request is verified.
If they do not match, reject the request.

Example Code (Ruby)

require 'openssl'
require 'active_support/security_utils'

def verify_signature(secret_string, timestamp, payload, signature)
  data = "#{timestamp}.#{payload}"
  secret = Base64.decode64(secret_string)
  digest = OpenSSL::HMAC.digest('SHA256', secret, data)
  expected_signature = Base64.strict_encode64(digest)

  ActiveSupport::SecurityUtils.secure_compare(expected_signature, signature)
end

Bank Account Data

Schema

eventenum<string>

dataobject

iduuid

The bank account id

employee_iduuid

The employee id

bsbstring

The bsb number of bank account

account_namestring

The account name of bank account

account_numberstring

The account number of bank account

primary_accountboolean

Determine bank account is primary or not

Callback Body

{  "event": "bank_account_created",  "data": {    "id": "78bc2d65-bf9e-434f-8b78-2367f56878ad",    "employee_id": "92ab2d65-cd9e-123d-2b71-1234d56878cd",    "bsb": "123123",    "account_name": "mew123",    "account_number": "123123",    "primary_account": false  }}

Certification Data

Schema

eventenum<string>

dataobject

iduuid

The certification id

namestring

The name of the certification

descriptionstring

The description of the certification

organisation_iduuid

The organisation id associated with the certification

Callback Body

{  "event": "certification_created",  "data": {    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",    "name": "First Aid Certificate",    "description": "Basic first aid and CPR certification",    "organisation_id": "c937993f-3573-40a7-a386-9f316b81b94a"  }}

Custom Field Data

Schema

eventenum<string>

dataobject

iduuid

The custom field id

namestring

The name of the custom field

hintstring

The hint of the custom field

descriptionstring

The description of the custom field

typeenum<string>

The type of the custom field

in_onboardingboolean

Returns true if the custom field captured during onboarding

organisation_iduuid

The organisation id associated with the custom field

requiredboolean

Returns true if the custom field is mandatory

custom_field_permissionsobject[]

Lists the permissions for the custom field

custom_field_optionsobject[]

Lists the options for the custom field when type is either single_select or multi_select

Callback Body

{  "event": "custom_field_created",  "data": {    "id": "922511dc-2af4-4513-83eb-960c2006aadc",    "hint": "Legal nationality as stated in identification documents",    "name": "Nationality",    "type": "single_select",    "required": true,    "description": "This field is typically the legal nationality as stated in identification documents.",    "in_onboarding": true,    "organisation_id": "c937993f-3573-40a7-a386-9f316b81b94a",    "custom_field_options": [      {        "id": "0d0cd804-578d-424d-a3ea-19b8d2bafd5c",        "value": "American"      },      {        "id": "985f4441-0f9d-4f68-a8e6-57a228167fde",        "value": "Australian"      },      {        "id": "773c0e77-811a-4e33-8865-e56814141547",        "value": "Vietnamese"      }    ],    "custom_field_permissions": [      {        "id": "1e807c07-4bf4-44d9-8477-d1e602060fda",        "role": "employee",        "permission": "editable"      },      {        "id": "db766044-b1a0-4688-9381-c6ef861efc16",        "role": "manager",        "permission": "editable"      },      {        "id": "41e0434a-722c-4626-8dcf-3badb5ff0cf0",        "role": "employee",        "permission": "viewable"      },      {        "id": "f3cfaa08-b3c9-42eb-8fed-9115679004b1",        "role": "manager",        "permission": "viewable"      }    ]  }}

Custom Form Response Data

Schema — Submitted / Approved / Declined

eventenum<string>

dataobject

iduuid

The custom form response id

organisation_iduuid

The organisation id

form_iduuid

The id of the custom form

form_namestring

The name of the custom form

member_iduuid

The id of the member who requested the form response

submitter_iduuid

The id of the member who submitted the form response

occurred_atdatetime

The timestamp when the event occurred

Schema — Partially Approved

eventenum<string>

dataobject

iduuid

The custom form response id

organisation_iduuid

The organisation id

occurred_atdatetime

The timestamp when the event occurred

approver_iduuid

The id of the member who approved this step

decliner_iduuid

The id of the member who declined this step

Callback Body — Submitted / Approved / Declined

{  "event": "custom_form_response_submitted",  "data": {    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",    "organisation_id": "c937993f-3573-40a7-a386-9f316b81b94a",    "form_id": "d4e5f6a7-b8c9-0123-def0-h45678901234",    "form_name": "Performance Review",    "member_id": "6902b0f2-f53a-466d-a9a0-073028716a3a",    "submitter_id": "5f212c81-9ae3-4267-8845-b3f8bbed10ad",    "occurred_at": "2026-05-07T10:30:00.000+00:00"  }}

Callback Body — Partially Approved

{  "event": "custom_form_response_step_approved",  "data": {    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",    "organisation_id": "c937993f-3573-40a7-a386-9f316b81b94a",    "occurred_at": "2026-05-07T11:00:00.000+00:00",    "approver_id": "6902b0f2-f53a-466d-a9a0-073028716a3a",    "decliner_id": null  }}

Employee Custom Field Data

Schema

eventenum<string>

dataobject

iduuid

The id of the custom field

employee_iduuid

The employee id

organisation_iduuid

The organisation id

valuestring | object[]

The value of the custom field filled in by your employee, it is a string when type is free_text and an array when type is single_select or multi_select

custom_fieldobject

Callback Body

{  "event": "employee_custom_field_updated",  "data": {    "id": "9e1898bf-0013-4682-b16e-0fc6a9c6a5bd",    "employee_id": "5f212c81-9ae3-4267-8845-b3f8bbed10ad",    "organisation_id": "c937993f-3573-40a7-a386-9f316b81b94a",    "value": [      {        "id": "773c0e77-811a-4e33-8865-e56814141547",        "value": "Vietnamese"      }    ],    "custom_field": {      "id": "922511dc-2af4-4513-83eb-960c2006aadc",      "name": "Nationality",      "type": "single_select",      "description": "This field is typically the legal nationality as stated in identification documents."    }  }}

Employee Data

Schema

eventenum<string>

dataobject

iduuid

The employee id

genderstring

The gender of the employee

countrystring

The country of employee (i.e AU, VI, US)

known_asstring

The preferred name of the employee

job_titlestring

The job title of the employee

last_namestring

The last name of the employee

first_namestring

The first name of employee

middle_namestring

The middle name of the employee

avatar_urlstring

The avatar URL of the employee

start_datestring

The start date of the employee

external_idstring

The external id of employee (Id of payroll system)

nationalitystring

The nationality of employee (i.e Australia, United States)

account_emailstring

The email of employee account

date_of_birthstring

The birthday of employee

personal_mobile_numberstring

The personal mobile number of employee

Callback Body

{  "event": "employee_created",  "data": {    "id": "f5e41ec5-b85d-486a-9bd0-ef9b04284c6e",    "gender": "male",    "country": "AU",    "known_as": "New employee",    "job_title": "Tii",    "last_name": "Please",    "first_name": "Yes",    "middle_name": "Midle Name",    "avatar_url": "/avatar.svg",    "start_date": "2020-02-27",    "external_id": "123-123-123",    "nationality": "Australia",    "account_email": "abc@def.com",    "date_of_birth": "1980-2-2",    "personal_mobile_number": "+2222222222"  }}

Employment History Data

Schema

eventenum<string>

dataobject

iduuid

The employment history id

titlestring

The job title

start_datedatetime

The start date of employment history

end_datedatetime

The end date of employment history

in_reviewboolean

Determine employment history is being reviewed or not

disabledboolean

Determine employment history is disabled or not

member_idstring

The member id of employment history

organisation_idstring

The organisation id of employment history

employment_typestring

The employment type of employment history (Full-time, Part-time, etc.)

declined_atstring

The time when employment history is declined

Callback Body

{  "event": "employment_history_created",  "data": {    "id": "4f6c7312-67ab-4775-ab2e-a3761ff56385",    "title": "Software Developer",    "disabled": false,    "end_date": "2021-12-09T00:00:00.000+00:00",    "in_review": false,    "member_id": "e826e79d-20d4-4b04-add2-8fa3c16cb7d8",    "start_date": "2021-02-17T00:00:00.000+00:00",    "declined_at": null,    "employment_type": null,    "organisation_id": "bdfcb02b-fcc3-4f09-8636-c06c14345b86"  }}

Goal Data

Schema

eventenum<string>

dataobject

iduuid

The goal id

organisation_iduuid

The organisation id associated with the goal

owner_iduuid

The id of the employee who owns the goal

namestring

The name of the goal

goal_typeenum<string>

The type of the goal

health_statusenum<string>

The status of the goal

progressnumber

The progress of the goal

due_datestring

The due date of the goal in YYYY-MM-DD format

parent_iduuid

The id of the parent goal, if any

group_iduuid

The id of the group (team) associated with the goal

archivedboolean

Returns true if the goal is archived. Archive/unarchive transitions are delivered as goal_updated, with this field reflecting the current state — there is no dedicated archive/unarchive event.

updated_atdatetime

The timestamp when the goal was last updated

Callback Body

{  "event": "goal_updated",  "data": {    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",    "organisation_id": "c937993f-3573-40a7-a386-9f316b81b94a",    "owner_id": "6902b0f2-f53a-466d-a9a0-073028716a3a",    "name": "Increase customer satisfaction score",    "goal_type": "company",    "health_status": "on_track",    "progress": 45,    "due_date": "2026-12-31",    "parent_id": null,    "group_id": "5f212c81-9ae3-4267-8845-b3f8bbed10ad",    "archived": false,    "updated_at": "2026-05-07T11:00:00.000+00:00"  }}

Key Result Data

Schema

eventenum<string>

dataobject

iduuid

The key result id

organisation_iduuid

The organisation id

goal_iduuid

The id of the goal this key result belongs to

owner_iduuid

The id of the member who owns this key result

namestring

The name of the key result

health_statusenum<string>

The status of the key result based on its progress towards the target value

start_valuenumber

The starting value of the key result

target_valuenumber

The target value of the key result

current_valuenumber

The current value of the key result

unitenum<string>

The unit of measurement for the key result values

sub_unitstring

The ISO-4217 currency code for the key result (e.g. AUD)

due_datestring

The due date of the key result in YYYY-MM-DD format

archivedboolean

Returns true if the key result is archived. Archive/unarchive transitions are delivered as key_result_updated events rather than a dedicated event

updated_atdatetime

The timestamp when the key result was last updated

Callback Body

{  "event": "key_result_updated",  "data": {    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",    "organisation_id": "c937993f-3573-40a7-a386-9f316b81b94a",    "goal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",    "owner_id": "6902b0f2-f53a-466d-a9a0-073028716a3a",    "name": "Increase quarterly revenue",    "health_status": "on_track",    "start_value": 0,    "target_value": 100,    "current_value": 45,    "unit": "monetary",    "sub_unit": "AUD",    "due_date": "2026-09-30",    "archived": false,    "updated_at": "2026-05-07T10:30:00.000+00:00"  }}

Time Off Request Data

Schema

eventenum<string>

dataobject

iduuid

Unique identifier for the object.

start_datestring

The start date of your employee time off request.

end_datestring

The end date of your employee time off request.

total_hoursnumber

The total hours of time off request.

total_unitsnumber

The total units of time off request.

unit_typestring

The unit type of time off request (e.g., days, hours).

hours_per_dayobject[]

Array of objects specifying custom hours for specific dates

commentstring

The comment of the time off request if an owner or admin has entered a notation

statusenum<string>

The status of time off request.

approvedboolean

The approve status of time off request

leave_balance_amountnumber

The leave balance amount of time off request.

leave_category_namestring

The category name of time off request object. I.E Annual Leave

reasonstring

The reason of employee's time off request.

employee_iduuid

The ID of employee who requested time off.

Callback Body

{  "event": "leave_request_approved",  "data": {    "id": "de00c577-35a1-4cf2-9fe8-832f18d4c544",    "reason": null,    "status": "Approved",    "comment": "",    "approved": true,    "end_date": "2025-10-22",    "unit_type": "days",    "start_date": "2025-10-15",    "employee_id": "6902b0f2-f53a-466d-a9a0-073028716a3a",    "total_hours": 0,    "total_units": 6,    "hours_per_day": [      {        "date": "2025-12-12",        "hours": 4      }    ],    "leave_category_name": "Annual Leave",    "leave_balance_amount": 1000  }}

Member Certification Data

Schema

eventenum<string>

dataobject

iduuid

The member certification id

certification_iduuid

The id of the associated certification

certification_namestring

The name of the associated certification

mandatoryboolean

Returns true if the certification is mandatory for the employee

statusenum<string>

The current status of the member certification

previous_statusenum<string>

The previous status of the member certification before the latest update

expiry_datestring

The expiry date of the member certification in YYYY-MM-DD format

employee_iduuid

The id of the employee who holds this certification

organisation_iduuid

The organisation id associated with the member certification

assigned_atdatetime

The timestamp when the certification was assigned to the employee

Callback Body

{  "event": "member_certification_approved",  "data": {    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",    "certification_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",    "certification_name": "First Aid Certificate",    "mandatory": true,    "status": "active",    "previous_status": "pending",    "expiry_date": "2027-03-12",    "employee_id": "6902b0f2-f53a-466d-a9a0-073028716a3a",    "organisation_id": "c937993f-3573-40a7-a386-9f316b81b94a",    "assigned_at": "2026-03-12T00:00:00.000+00:00"  }}

Timesheet Entry Data

Schema

eventenum<string>

dataobject

iduuid

The unique identifier for the timesheet entry

datestring

The date of the timesheet entry in YYYY-MM-DD format

timenumber

The time value of the timesheet entry in seconds

emailstring

The email address of the member

unitsnumber

The units for the timesheet entry

breaksobject[]

Array of break periods within the timesheet entry

statusenum<string>

The status of the timesheet entry

commentstring

Any comment associated with the timesheet entry

end_timedatetime

The end time of the timesheet entry

member_iduuid

The member ID

created_atdatetime

The timestamp when the timesheet entry was created

created_byuuid

The ID of who created the timesheet entry

start_timedatetime

The start time of the timesheet entry

updated_atdatetime

The timestamp when the timesheet entry was last updated

approved_byuuid

The ID of who approved the timesheet entry

location_iduuid

The location ID associated with the timesheet entry

organisation_iduuid

The organisation ID

rostered_shift_iduuid

The scheduled shift ID associated with the timesheet entry

Callback Body

{  "event": "timesheet_entry_created",  "data": {    "id": "00d495cc-740e-4e4d-8091-3588b267e847",    "date": "2027-01-16",    "time": 45000,    "email": "employee@example.com",    "units": 12.5,    "breaks": [      {        "end_time": "2027-01-16T11:30:00.000+11:00",        "start_time": "2027-01-16T10:45:00.000+11:00"      }    ],    "status": "pending",    "comment": null,    "end_time": "2027-01-16T23:45:00.000+11:00",    "member_id": "58a62b9b-cd44-4d69-94d1-0742876e0ea8",    "created_at": "2026-01-14T14:30:51.891+11:00",    "created_by": "58a62b9b-cd44-4d69-94d1-0742876e0ea8",    "start_time": "2027-01-16T10:30:00.000+11:00",    "updated_at": "2026-01-14T14:30:51.955+11:00",    "approved_by": "6902b0f2-f53a-466d-a9a0-073028716a3a",    "location_id": "24b7aad8-0420-4380-9772-cfd78d5a7aad",    "organisation_id": "c37482a7-57ff-4e37-b587-c3038d714fe0",    "rostered_shift_id": "f4e1c4d3-2f4b-4e2a- ninth-123456789abc"  }}