Leveraging UKG HR Service Delivery webhooks¶

Note

UKG HR Service Delivery provides webhooks that are easy to configure and enable realtime notifications. This document will help you understand what webhooks are, by walking you through a selection of real-life examples, and configure your first webhook.

Prerequisites
What are webhooks
Why use webhooks?
Events for webhooks
- List of available events
- Examples of use-cases and events to use
Configuring your first UKG HR Service Delivery webhook

Prerequisites ¶

You need to understand how authenticating to UKG HR Service Delivery APIs works. Read this guide if you do not feel comfortable with this topic before going further.
Webhooks require that you expose your target environment to the Internet, so that UKG HR Service Delivery messages can be received and processed. To know more read below.

What are webhooks ¶

Webhooks allow you to build or set up integrations, which subscribe to certain events from UKG HR Service Delivery. When one of those events is triggered, UKG HR Service Delivery sends an HTTP POST callback to the webhook’s configured URL of choice.

In other words, rather than polling on a regular basis the target API of your choice, you simply configure a webhook to be notified that the expected action/event actually happened, in real-time.

With the UKG HR Service Delivery webhooks, you can for example be notified when a user or employee profile changes, after the creation of a document, or for the e-signature of a document.

The list of events you can subscribe to is available in the following section.

You can read more about webhooks on the Zapier Blog.

Why use webhooks?¶

To put it simply, webhooks are made to simplify your API integration by giving you the freedom to avoid polling and managing various types of answers from the target system. Take the following API implementation scenario:

“You generate documents using UKG HR Service Delivery APIs, create a process for employees to sign the documents, and want to know when the documents are signed and sealed to store them into your CoreHR of choice”

Without UKG HR Service Delivery webhooks, your API flow would look like this:

In this case:

Your integration needs to handle recurrent requests until your system gets the expected response.
Your implementation needs you to manage potential unexpected answers and errors from UKG HR Service Delivery APIs (although we provide high SLAs).

These operations are time consuming, can lead to complex implementations and consume useless amounts of bandwidth.

Now, have a look at the same described scenario, only relying on a webhook configured for your instance:

As you can see, once configured, webhooks are a powerful feature that enables you to get notified when asynchronous tasks have to be completed.

Events for webhooks ¶

List of available events ¶

Resource type	Resource code	Events	Details	Usage
Core data
Account	`account`	created	The account has been created	`account.created`
		updated	The account has been updated	`account.updated`
		deleted	The account has been deleted	`account.deleted`
		logged_in	The corresponding user has logged in	`account.logged_in`
Employee	`employee`	created	The employee has been created	`employee.created`
		updated	The employee has been updated	`employee.updated`
		deleted	The employee has been deleted	`employee.deleted`
		restored	The employee has been restored after having been deleted	`employee.restored`
User	`user`	created	The user has been created	`user.created`
		updated	The user informations have been updated, or a profile has been updated, created or deleted	`user.updated`
		deleted	The user has been deleted	`user.deleted`
Import	`import`	created	The import is created but hasn’t started yet	`import.created`
		started	The system has started processing this import	`import.started`
		completed	The processing is done. You can refer to the status of the import to know whether it was a success or not	`import.completed`
Dataset import	`dataset_import`	created	A dataset import has been created	`dataset_import.created`
Dataset	`dataset`	created	The dataset has been created	`dataset.created`
Dataset	`dataset`	updated	The dataset has been updated	`dataset.updated`
Dataset value	`dataset_value`	created	The dataset value has been created \| `dataset_value.created`
		updated	The dataset value has been updated \| `dataset_value.updated`
		deleted	The dataset value has been deleted	`dataset_value.deleted`
Organization	`organization`	created	The organization has been created	`organization.created`
		updated	The organization has been updated	`organization.updated`
		deleted	The organization has been deleted	`organization.deleted`
Organization group	`organization_group`	created	The organization group has been created	`organization_group.created`
Organization group	`organization_group`	updated	The organization group has been updated	`organization_group.updated`
Custom fields	`custom_fields`	created	The custom field has been created	`custom_fields.created`
		deleted	The custom field has been deleted	`custom_fields.deleted`
		updated	The custom field has been updated	`custom_fields.updated`
SAML Identity provider	`saml_identity_provider`	created	The SAML Identity provider has been created	`saml_identity_provider.created`
		updated	The SAML Identity provider has been updated	`saml_identity_provider.updated`
		deleted	The SAML Identity provider has been deleted	`saml_identity_provider.deleted`
Document Manager data
Electronic vault link	`electronic_vault_link`	deleted	The employee and his/her vault are unlinked. The employee’s vault still exist but is unlinked this company	`electronic_vault_link.deleted`
Role permissions not included	`role`	created	The role has been created	`role.created`
		deleted	The role has been deleted	`role.deleted`
		updated	The role has been updated (but not permissions) \| `role.updated`
Document generation	`document_generation`	created	The document has been generated \| `document_generation.created`
Document generation template	`document_generation_template`	created	The document template has been created	`document_generation_template.created`
		updated	The document template has been updated	`document_generation_template.updated`
		deleted	The document template has been deleted	`document_generation_template.deleted`
Document generation template version	`document_generation_template_version`	created	The document template version has been created	`document_generation_template_version.created`
		activated	The document template version has been activated	`document_generation_template_version.activated`
		deactivated	The document template version has been deactivated	`document_generation_template_version.deactivated`
Signature types	`signature_type`	created	The signature type has been created	`signature_type.created`
		updated	The signature type has been updated	`signature_type.updated`
		deleted	The signature type has been deleted	`signature_type.deleted`
Signature processes ‘expired’, ‘canceled’ and ‘rejected’ are not included	`signature_process`	created	The signature process has been created	`signature_process.created`
		sent	The signature process has been sent (not archived; Only applicable if there is an external signatory in the signature process)	`signature_process.sent`
		updated	The signature process has been updated (applicable at process level; not applicable at each signatory level)	`signature_process.updated`
		signed	The document has been signed by one signatory (only after a POST /signature_processes/{signature_process_id}/send)	`signature_process.signed`
		completed	The signature process has been completed (only after a POST/signature_processes/archive for an external)	`signature_process.completed`
		deleted	The signature process has been deleted	`signature_process.deleted`
Employee Document	`employee_document`	created	The employee document has been created	`employee_document.created`
		deleted	The employee document has been deleted	`employee_document.deleted`
		restored	The employee document has been restored	`employee_document.restored`
		trashed	The employee document has been trashed	`employee_document.trashed`
		updated	The employee document has been updated	`employee_document.updated`
		unlinked	The employee document has been unlinked	`employee_document.unlinked`
Company Document	`company_document`	created	The company document has been created	`company_document.created`
		deleted	The company document has been deleted	`company_document.created`
		restored	The company document has been restored	`company_document.created`
		trashed	The company document has been trashed	`company_document.created`
		updated	The company document has been updated	`company_document.created`
Legalhold	`legalhold`	created	The legalhold has been created	`legalhold.created`
Legalhold	`legalhold`	deleted	The legalhold has been deleted	`legalhold.deleted`
Employee document type	`employee_document_type`	created	The employee document type has been created	`employee_document_type.created`
Employee document type	`employee_document_type`	updated	The employee document type has been updated	`employee_document_type.updated`
Company document type	`company_document_type`	created	The company document type has been created	`company_document_type.created`
Company document type	`company_document_type`	updated	The company document type has been updated	`company_document_type.updated`
People Assist data
Generated document (in Process automation task)	`workingfile`	signed	The document has been signed by an HR user or by an employee	`workingfile.signed`
		created	The document has been created	`workingfile.created`
		updated	A fill_pdf task attached to the document has been completed by an HR user or by an employee	`workingfile.updated`
		sealed	The document has been digitaly signed. It can’t be modified without breaking this signature	`workingfile.sealed`
Request	`request`	created	The request has been created	`request.created`
		updated	The request has been updated	`request.updated`
		deleted	The request has been deleted	`request.deleted`
Process	`process`	created	The process has been created	`process.created`
		published	The process has been published	`process.published`
		completed	The process has been completed	`process.completed`
		finalized	The process has been closed	`process.finalized`
		hidden	The process has been hidden in the users and employees interfaces	`process.hidden`
Platform events
Deletion request	`deletion_request`	created	The deletion request has been created (only for employee)	`deletion_request.created`
		confirmed	The deletion request has been confirmed after evaluation	`deletion_request.confirmed`
		canceled	The deletion request has been canceled after evaluation	`deletion_request.canceled`
		prepared	The deletion request has been sent to the owner of the resource (only for employee)	`deletion_request.prepared`
		completed	The deletion request has been completed : the resource is deleted	`deletion_request.completed`
		failed	The deletion request has failed	`deletion_request.failed`
Retention policies for People Assist	`retention_policy`	created	The retention policy has been created	`retention_policy.created`
Retention policies for People Assist	`retention_policy`	deleted	The retention policy has been deleted	`retention_policy.deleted`
Webhooks	`webhooks`	created	A webhook has been created	`webhooks.created`
		deleted	A webhook has been deleted	`webhooks.deleted`
		updated	A webhook has been updated	`webhooks.updated`

Examples of use-cases and events to use ¶

Use Case description	Events to configure in your webhook
You want to monitor and store every platform configuration changes that occur in UKG HR Service Delivery	account.* employee.* organization*
When documents are created (filled on our system) and sent for signature, get updates on this process to fetch the finalized documents	document_generation.created signature_tasks.signed
For every employee data created or updated, fetch it’s data and import it into your coreHR	employee.created employee.updated

Configuring your first UKG HR Service Delivery webhook ¶

Note

Webhooks API specifications are available in UKG HR Service Delivery OpenAPI specifications.

Configure the webhook ¶

The first step to setup your webhook is to POST its configuration.

See below:

{
  "name": "My webhook to receive events on my application",
  "callback_url": "https://myapp.com/peopledoc-webhooks",
  "events": [
    "employee.created",
    "signature_tasks.signed"
  ],
  "is_active": "true"
}

Here, you are creating webhooks triggered:

When and employee profile is created

Whenever a signature event occurs through Digital Process Manager.

Note

UKG HR Service Delivery webhooks support wildcards. This enables you to subscribe to a group of events from a specific event category, rather than one event/action at the time. For example: employee.*.

If your request is successful, UKG HR Service Delivery webhooks API returns:

{
  "name": "My webhook to receive events on my application",
  "callback_url": "https://myapp.com/peopledoc-webhooks",
  "events": [
    "employee.created",
    "signature_tasks.signed"
  ],
  "is_active": "true",
  "id": "5cf2b3a3-04a0-418f-8d8c-914e543f44ea",
  "signature_key": "stUIMviAfCGahM8kqp5EYa1aBLgZ22ES",
  "created_at": "2019-12-02T13:44:19.025+00:00",
  "updated_at": "2019-12-02T13:44:19.025+00:00"
}

Secure your webhook ¶

Webhooks require that you open at least one callback URL.

In order to help you check the authenticity of the calling service, UKG HR Service Delivery provides a signature_key as below:

{
  // [...]
  "signature_key": "stUIMviAfCGahM8kqp5EYa1aBLgZ22ES",
  // [...]
}

Once your webhook is created, you can safely store this key to check its authenticity.

Note

This signature key can be regenerated at any time, using the /webhooks/{id}/refresh_signature_key endpoint.

Read more about the Refresh Signature Key endpoint specifications.

Checking webhooks authenticity¶

As stated previously, when you register for a new webhook, you are provided a “signature_key.”

This key is unique to the webhook, and can be considered as a trust certificate.

To protect yourself, compare the expected signature to each of the received signatures, as well as the webhook ID.

Testing your webhooks callback URL ¶

Webhooks require that you provide a “public” (exposed) URL to receive them.

To test that your system is open to UKG HR Service Delivery callbacks, use the following API endpoint:

POST /webhooks/{id}/tests

Assuming you have previously created a webhook, post on this endpoint, using the right webhook ID, to check that your network allows incoming calls from UKG HR Service Delivery webhook API.

This endpoint generates a “fake” webhook callback, using your provided configuration.

Receiving callbacks on your local development environment¶

Once you’ve understood and configured your first webhook, it is common practice to test the callbacks with your application, to make sure everything respects your implementation’s requirements.

The one difficulty is that when you are developing an application that consumes webhooks you need a publicly accessible URL to configure the webhook service with.

Typically you would develop on localhost and the rest of the world would have no access to your application, so how do you test your webhooks?

Tip

To receive webhooks callbacks in a secure way, we suggest SSH tunneling.

Applications such as ngrok allow easy configuration and debugging tools to check that both the callbacks and your consumer application behave as expected.

Have a look at the ngrok documentation to know more and receive your first callbacks on your localhost.

Testing your webhook callback on your localhost, using Ngrok and Postman¶

As explained previously, you can easily configure and test webhooks and their callbacks.

Below, you can see how easy and fast it is, using Postman, Ngrok, and the following endpoints:

POST /webhooks to create your webhook;
POST /webhooks/{id}/tests to check your configured callback URL; UKG HR Service Delivery instantly sends a test payload back to the configured URL, for example localhost.