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 the related guide if needed.
• Webhooks require that you expose your target environment to the Internet, so that UKG HR Service Delivery messages can be received and processed.

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.

For example, you can be notified when a user or employee profile changes, after the creation of a document, or for the e-signature of a document.

Why use webhooks?

To simplify your API integration by avoiding polling and managing various types of responses from the target system. Instead of repeatedly checking for updates, you configure webhooks to notify your system when relevant events occur—for example, when a document is signed and sealed so you can store it in your CoreHR system.

Events for webhooks

List of available events

Examples of use-cases and events to use

• Monitor and track all platform configuration changes using events like account.*, employee.*, and organization.*.
• After document creation and signature, fetch finalized documents using document_generation.created and workingfile.signed.
• For new or updated employee data, sync it to your CoreHR using employee.created and employee.updated.

Configuring your first UKG HR Service Delivery webhook

Configure the webhook

To set up a webhook, send a POST request with the following JSON payload to configure:

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

This configures webhook triggers for when an employee profile is created and when a signature event occurs.

Note: UKG HR Service Delivery webhooks support wildcards (e.g., employee.*) to subscribe to multiple related events.

On success, the API returns:

{
  "name": "My webhook to receive events on my application",
  "callback_url": "https://myapp.com/peopledoc-webhooks",
  "events": [
    "employee.created",
    "workingfile.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. The API provides a signature_key to help verify authenticity. You should store this key and use it to validate incoming requests.

Note: You can regenerate the signature key using the /webhooks/{id}/refresh_signature_key endpoint.

Checking webhook authenticity

Compare the expected signature with each received one, and verify the webhook ID to confirm authenticity.

Testing your webhooks callback URL

To test your webhook endpoint, use the endpoint:
POST /webhooks/{id}/tests

This generates a fake webhook callback to help validate that your network accepts incoming calls from UKG HR Service Delivery.

Receiving callbacks on your local development environment

Since your app may run on localhost, you need a public endpoint to receive callbacks. You can use SSH tunneling or utilities like ngrok to test webhooks locally. Refer to ngrok documentation for setup guidance.

Testing with Ngrok and Postman

Use common tools like Postman and ngrok to create the webhook (POST /webhooks) and test its callback endpoint (POST /webhooks/{id}/tests). UKG HR Service Delivery will send a test payload to your configured URL, even if it’s localhost.