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¶
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¶
Event Category |
Events available |
Platform events |
|
account |
|
employee |
|
token |
|
import |
|
dataset |
|
dataset_value |
|
dataset_import |
|
organization |
|
organization_group |
|
legalhold |
|
webhooks |
|
Document Manager events |
|
user |
|
role |
|
document_generation |
|
document_generation_template |
|
document_generation_template_version |
|
signature_types |
|
employee_document |
|
company_document |
|
employee_document_type |
|
company_document_type |
|
People Assist events |
|
signature_tasks |
|
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 |
|
When documents are created (filled on our system) and sent for signature, get updates on this process to fetch the finalized documents |
|
For every employee data created or updated, fetch it’s data and import it into your coreHR |
|
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.
