Webhook

This explains how you can use the profile webhook to keep your surrounding systems up to date.

Save time and increase data quality by automating profile updates to any other system – a simple way to import and keep people synchronized between your organization in Huma and your other systems or services.

The formats can be subject to change.

Supported features

  • Export current state of user profiles
    To initialise state for the system connecting by webhook, exporting will send updates for each employee with all current field values.
  • Automatically receive real-time updates when a profile is changed in Huma
    Changes made in the supported profile fields (listed below) will be automatically sent as updates to the url registered.
  • Automated updates when users are added or removed
    Whenever a user is created or deleted in Huma, a message is automatically sent to the url registered.

How to use the webhook

To get started, simply provide an url which can receive the requests the webhook will send. You can also register a client secret and/or an access token.

  • If the client secret is set, each request will include a header [huma-hmac-sha256] with a hash of the json body, signed with the secret to verify the message.
  • If the access token is set, each request will include it as a standard bearer token.
All requests include a [huma-topic] header, as well as a json body containing a [topic] property. The value of header [huma-topic] and body property [topic] will be identical, and will be one of:
  • users-create
  • users-update
  • users-delete
  • users-export

All request bodies also include a [users] array, which contains an object for each affected user. These objects will always contain:

  • id
    • Always present
    • A unique identifier for the user
      • This value will remain unchanged over the user’s lifetime.
    • Value is a standard 128-bit UUID (see rfc4122)
  • email
    • Always present
    • A unique identifier at the point where the request is sent: no two users can have the same email
      • Note that a user’s email can be changed by a user with the appropriate permission, so a user is not guaranteed to have the same value in later requests.
    • Value is a string, validated to be an email address
  • employmentId
    • Present if set, absent if the user does not have one
    • A unique identifier at the point where the request is sent: no two users can have the same employment ID
      • Note that a user’s employment ID can be changed, or removed, by a user with the appropriate permission, so a user is not guaranteed to have the same value in later requests.
    • Value is a string, no restriction other than uniqueness within the organization

Be aware, if a request is not handled within 1 second, it will time out, so it may be useful to persist received data and respond, then do any further work to the data in a separate process.

Create

A user or users being created in your Huma account is sent as a [POST] request, with full profile objects for the created users in the [users] array.

For example:

{
"topic": "users-create",
"users": [
{
"id": "09d41e51-0963-4763-933b-8c9df093d653",
"givenName": "Ida",
"familyName": "Fossdal",
"email": "ida.fossdal@godmat.no",
"phone": "+47 955 55 167",
"address": {
"line1": "Fossvegen 82",
"line2": null,
"postalCode": "1823",
"city": "Bergen",
"country": "NO"
},
"birthDate": "1993-07-29",
"bankAccount": {
"type": "national",
"number": "12345678903",
"country": ""
},
"gender": "Female",
"employmentId": "1",
"employmentStartDate": "2001-09-14",
"employmentEndDate": null,
"employmentType": "Permanent",
"employmentPercentage": 100
},
{
"id": "d96434d7-9506-4d5f-a969-7d1eea8bc3d6",
"givenName": "Jesper",
"familyName": "Blom",
"email": "jesper.blom@godmat.no",
"phone": "+46 7555512",
"address": {
"line1": null,
"line2": null,
"postalCode": "520 43",
"city": "Stockholm",
"country": "SE"
},
"birthDate": "1989-09-08",
"bankAccount": null,
"gender": "Male",
"employmentId": "31",
"employmentStartDate": "2019-01-01",
"employmentEndDate": null,
"employmentType": "Permanent",
"employmentPercentage": 100
}
]
}

Delete

A user or users being deleted in your Huma account is sent as a [DELETE] request, with the [users] object(s) containing only identifiers.

For example:

{
"topic": "users-delete",
"users": [
{
"id": "d5430b67-479c-456a-b2c4-4053789d2959",
"email": "ida.fossdal@godmat.no",
"employmentId": "1"
}
]
}

 

Update

A regular update is sent as a [PATCH] request, with the [users] object(s) containing only identifiers and the actually changed field(s).

For example, an employee changing their bank details to use IBAN:

{
"users": [
{
"id": "d96434d7-9506-4d5f-a969-7d1eea8bc3d6",
"email": "jesper.blom@godmat.no",
"employmentId": "31",
"bankAccount": {
"type": "international",
"iban": "FR7630006000011234567890189",
"bic": "AGRIFRPP"
}
}
],
"topic": "users-update"
}

Export

An export is sent as one or more POST request(s), each detailing the full state of all fields supported by the webhook for all users, including empty values for fields that have not been set. Each request details up to 50 profiles, so if your organization has more than 50 users, the export will be sent as multiple requests. E.g. an export from an organizations with 132 users would receive three requests, the first two with 50 user objects each, followed by a final request with 32 user objects.

For example:

{
"topic": "users-export",
"users": [
{
"id": "c2c8d497-352a-4c21-bf7c-aefbaec37717",
"givenName": "Patrick",
"familyName": "Remen",
"email": "patrick.remen@godmat.no",
"phone": "+46 7455564",
"address": {
"line1": null,
"line2": null,
"postalCode": "464 95",
"city": "Stockholm",
"country": "SE"
},
"birthDate": "1987-02-13",
"bankAccount": null,
"gender": "Male",
"employmentId": "30",
"employmentStartDate": "2012-03-13",
"employmentEndDate": null,
"employmentType": "Permanent",
"employmentPercentage": 100
},
{
"id": "12b87a11-7b5a-4c77-bef2-f46522d99e1c",
"givenName": "Laila",
"familyName": "Støa",
"email": "laila.stoa@godmat.no",
"phone": "+47 455 53 217",
"address": {
"line1": "Kleivbakken 21",
"line2": null,
"postalCode": "2412",
"city": "Bergen",
"country": "NO"
},
"birthDate": "1981-08-04",
"bankAccount": {
"type": "national",
"number": "12345678902",
"country": ""
},
"gender": "Female",
"employmentId": "2",
"employmentStartDate": "1999-05-18",
"employmentEndDate": null,
"employmentType": "Permanent",
"employmentPercentage": 60
},
{
"id": "d96434d7-9506-4d5f-a969-7d1eea8bc3d6",
"givenName": "Jesper",
"familyName": "Blom",
"email": "jesper.blom@godmat.no",
"phone": "+46 7555512",
"address": {
"line1": null,
"line2": null,
"postalCode": "520 43",
"city": "Stockholm",
"country": "SE"
},
"birthDate": "1989-09-08",
"bankAccount": {
"type": "international",
"iban": "FR7630006000011234567890189",
"bic": "AGRIFRPP"
},
"gender": "Male",
"employmentId": "31",
"employmentStartDate": "2019-01-01",
"employmentEndDate": null,
"employmentType": "Permanent",
"employmentPercentage": 100
}
]
}

Be aware, if a request is not handled within 1 second, it will time out, so it may be useful to persist received data and respond, then do any further work to the data in a separate process.

Supported fields

These are the profile fields that the webhook will send updates about:


Security & compliance

By connecting with webhooks, you authorize Huma to access your webhooks account as described in our Terms of Service under Third-Party Platforms.

The webhook and other integrations require a Business or Enterprise subscription