UKG Webhooks User Guide

Caveats and Disclaimers

UKG Webhooks is dependent on UKG Pro events enablement. There are certain scenarios where events that you can subscribe to will not be delivered:

• Trigger removal or disablement. If your company uses consultants or internal developers that can disable or remove SQL triggers attached to tables in Pro, those events will not be sent to our UKG Webhooks application during that time when the triggers were removed or disabled. The result is we cannot send the event notification to your configured endpoint URL.
• SQL access and database restores. There are certain scenarios where a database restore needs to happen. During that time, there could be a short amount of time where the triggers are disabled and events will not be sent to our UKG webhooks application. The result is we cannot send the event notification to your configured endpoint URL.
• If you are performing mass updates to your company database and you do not want to be notified of those changes during that update, it would be recommended for you to temporarily mark your subscriptions as inactive during that period.
• If you are creating a business critical integration based on a UKG Webhooks notification that has zero tolerance for a missed event, you should consider a secondary polling synchronization or nightly report. This would safeguard you from missing any change that may happen in PRO that you have subscribed to. We do have plans to implement a replay of events that failed to be delivered, but this would require you to periodically check for those and submit the replay from UKG webhooks application. The retention time for all events in UKG Webhooks is 14 days (about 2 weeks). When a subscription is no longer needed, you may delete it.

Log in to UKG Webhooks

Log in to the UKG Webhooks application to subscribe to events.

1. For US Customers, enter https://webhooks.ukg.net in your browser. For Canadian customers enter https://webhooks-ca.ukg.net
2. Enter the company access code.
   • To create a company access code, refer to: Create a Company Access Code
3. Select Next.
4. Enter your username and password.
5. Select Sign In.

The UKG webhooks application appears.

Create a Company Access Code

To create a company access code, log in to Pro as an Administrator and use the following steps:

1. Navigate to Menu > System Configuration > System Settings > Mobile App and Chat Integrations.
2. On the Mobile App and Chat Integrations page, click the Edit (pencil) icon.
3. On the Edit page, enable the Enable Classic Mobile App field and disable all other fields.
4. Update the Company Access Code field with your company access code.
5. Save the form.
   • Note: After clicking Save, a warning that you cannot update the company access code once it has been created will appear. Acknowledge the warning and Save the form.

Once complete, this creates the Classic Mobile App. To generate a company access code without creating the Classic Mobile App, first perform the procedure above, then perform the following additional steps:

1. On the Mobile App and Chat Integrations page, click the Edit (pencil) icon.
2. On the Edit page, disable the Enable Classic Mobile App field and leave all other fields disabled.
3. Save the form.

Once these steps are complete, a company access code will be created without activating mobile or sending any unwanted notifications.

Configure Role-Based Access

The UKG Webhooks web application incorporates Role-Based Access Control (RBAC) with three primary roles:

• Admin:
  • Users with this permission in Pro Suite have full control over the application, including the creation and management of user roles and permissions specific to UKG Webhooks application.
  • Admins are authorized by checking against the permission in PRO for Service Account Administration > Add/Edit Service Account. For more information, refer to: Designate an Administrator.
• Editor:
  • Users with this role can manage webhooks subscriptions (create/edit/delete) and webhooks logs and analytics but cannot alter user roles or permissions.
  • Editors are authenticated via Pro Identity; the Editor role is relevant only to UKG Webhooks (this role does not exist in UKG Pro).
• Viewer:
  • Users with this role are limited to read-only access when viewing webhooks subscriptions, configurations, and logs.
  • Viewers are authenticated via Pro Identity; the Viewer role is relevant only to UKG Webhooks (this role does not exist in UKG Pro).

Designate an Administrator

To designate a user as a UKG Webhooks administrator:

1. Access your instance of Pro and navigate to System Configuration > Security > User Administration.
2. Add a role containing Web Access Rights for "Add/Edit Service Accounts" with "Add" permission.

Once this Admin role is added to the employee of your choice, they will be able to create Viewers and Editors within the UKG Webhooks application.

Add, Edit, or Delete Users

To add, edit, or delete a user, log into the UKG Webhooks application as a user with the Admin role and use the following steps:

1. From the Webhooks dashboard, click the access management icon in upper right corner (only visible by users with the Admin role). The Access Management dialog opens.
2. In the Access Management window:
   a. Add a user by searching for them using their designated e-mail address.
   b. Edit a user by selecting their name from the list of Current Users.
   c. Delete a user by clicking the Delete Icon next to the user's name in the Current Users list.
3. When adding or editing a user, you have the option to modify the following details:
   a. The user's first name.
   b. The user's last name.
   c. Selecting Viewer or Editor determines the user's role within UKG Webhooks.
   d. Enabling the Active checkbox turns the user profile on, thereby providing the user with access to UKG Webhooks.
4. Click Save to apply your changes or Close to discard your changes.

Add a Subscription

Add a subscription to send notifications of specific events from the UKG Pro solution. When configuring a subscription, you may choose to enter a Hash-based Message Authentication Code (HMAC) secret for Webhook message verification. You may also choose to further customize your webhook requests using free-form headers.

1. From the UKG Webhooks application, select the Add Subscription button.
2. Enter a subscription name.
3. Enter the endpoint URL that will receive the event notifications.
4. (Optional) To secure the subscription, at the Add HMAC Secret field, enter a HMAC secret with a minimum of 24 characters. Be sure to record the HMAC secret. You may use the Copy icon to copy and paste it. Once you save the subscription, you cannot view or edit the HMAC secret, you can only generate a new one.
5. (Optional) At the Add Free Form Headers fields, enter a custom header key and custom header value.
6. (Optional) Select the Plus icon to add additional custom header keys and values, as needed.
7. From the Available Events section, select the boxes next to the events for which you want to receive notifications.
8. Select the right arrow icon to move the events to the Selected Events section. To remove an event from the Selected Events section, uncheck the box and select the left facing arrow icon.
9. (Optional) To create this subscription in an inactive state, select the Save this Subscription as Inactive box.
10. Select Save.

The Subscription section displays the new subscription.

Subscription Edits

You can update a subscription at any time by selecting the Ellipsis icon for the associated subscription and selecting Edit.

When making updates to a subscription, keep the following in mind:

• If you need to update an HMAC secret or you do not know what it is, you must enter a new secret.

Test an Endpoint

Test your subscription's endpoint to ensure notifications can be received.

1. From the Subscription section of the UKG Webhooks application, select the Ellipsis icon for the subscription you wish to test.
2. Select Test Endpoint.
3. The test event's title and timestamp appear in the subscription's Last Event and Last Event Delivered (UTC) columns.
4. Select the subscription to view the status of the test in the Events section.

If the test was successful, a test notification is sent to the endpoint URL.

(Optional) Verify an HMAC Secret

If your subscription was secured using an HMAC Secret, verify the HMAC secret to ensure the subscription is secure. For more information on verifying HMAC signatures, including examples for each programming language, see the SVIX open source documentation.

Note: Whenever the prefix "svix" appears in the SVIX open source documentation, it must always be changed to "webhooks". For example: "svix_id" becomes "webhooks_id".

Event Details

To view the events from a subscription, select the subscription. The Events grid shows all the subscription's events.

The grid displays the event's status, timestamp, and name. To view the information contained in the event's payload, select the event. The event's payload appears in the Event Payload section.

For more information about events, refer to the UKG Webhooks Events Catalog.

Deactivate a Subscription

To stop receiving notifications for a particular subscription, you may deactivate the subscription.

1. From the Subscription section of the UKG Webhooks application, select the Ellipsis icon for the subscription you wish to deactivate.
2. Select Deactivate.

The subscription's status updates to InActive and displays a red icon.

Delete a Subscription

When a subscription is no longer needed, you may delete it.

1. From the Subscription section of the UKG Webhooks application, select the Ellipsis icon for the subscription you wish to delete.
2. Select Delete.

The subscription is deleted.