Documentation
What's NewUKG.comMarketplaceUKG Pro status

Creating an Endpoint URL for UKG Webhooks

Introduction

In this document, we will explain what it means to create an endpoint URL for a webhook in simple, non-technical terms. Webhooks are a way for different software systems to communicate with each other automatically. Creating an endpoint URL is an essential step in setting up a webhook. Additionally, we will guide you on how to consume the webhook payload and use that data to automate business processes with subsequent API (Application Programming Interface) calls to other SaaS (Software As A Service) providers you may utilize.

What is a Webhook?

A webhook is like a digital message that gets sent from one system to another when something specific happens. For example, if you receive a new message on a social media platform, a webhook can automatically send that information to another system, like an email or a chat application.

What is an Endpoint URL?

An endpoint URL is like a digital mailbox where these webhook messages are sent. It is a web address (URL) that tells the system where to deliver the webhook messages. When you create an endpoint URL, you’re setting up this digital mailbox to receive the information you want.

Steps to Create an Endpoint URL

1. Choose a Platform

First, decide where you want to receive the webhook messages. This could be a website, an application, or a service that can handle webhooks. Here are some common platforms:

  • Zapier
  • IFTTT
  • Microsoft Teams
  • ServiceNow
  • Salesforce
  • Postman

2. Set Up Your Endpoint With Chosen Platform

Using Zapier

To set up your endpoint with Zapier, use the following steps:

  1. Sign in to Zapier.
  2. Create a New Zap: Look for an option to create a new Webhook or custom trigger.
  3. Select Webhooks by Zapier: Choose the Webhook option when prompted.
  4. Copy the URL: The service will provide you with a unique URL. This is your endpoint URL.

Using IFTTT

To set up your endpoint with IFTTT, use the following steps:

  1. Sign in to IFTTT.
  2. Create a New Applet: Click Create to start a new applet.
  3. Click + this and search for “Webhooks”.
  4. Select “Receive a web request” as the trigger.
  5. Enter an Event Name (e.g., incoming_webhook).
  6. Click Create trigger.
  7. Click + that to define what happens when the Webhook is received.
  8. Select the service and action you want to perform when the Webhook is triggered (e.g., send an email, create a spreadsheet row, etc.).
  9. Click Finish to complete the configuration.
  10. Copy the URL: Go to the Webhooks service page on IFTTT, click Documentation, and copy the URL provided, for example:https://maker.ifttt.com/trigger/{event_name}/with/key/{your_key}.

Using Microsoft Teams

To set up your endpoint with Microsoft Teams, use the following steps:

  1. Open MS Teams and log in with your account.
  2. Navigate to the channel where you want to receive the Webhook messages.
  3. Click on the ellipsis (...) next to the channel name and select Connectors to add a connector.
  4. In the connectors list, search for Incoming Webhook.
  5. To add an incoming Webhook, click Add and then Add to a team.
  6. Configure the Webhook:
    • Use the Name field to give your Webhook a meaningful name.
    • Click Create to generate the Webhook URL.
  7. Copy the generated Webhook URL which will be used to send data to the MS Teams channel.

Using ServiceNow

To set up your endpoint with ServiceNow, use the following steps:

  1. Go to your ServiceNow instance and log in with an account that has administrative privileges.
  2. To view your Scripted Rest APIs, navigate to System Web Services > Scripted REST APIs or search for Scripted REST APIs in the application navigator.
  3. Click New to create a Scripted REST API:
    • Name: Give your API a meaningful name.
    • API ID: This will be auto-generated based on the name.
    • Base API Path: Define a base path for your API. For example: /api/webhook.
  4. Within the newly created API, click New under the Resources related list to add a resource:
    • Name: Give your resource a name.
    • HTTP Method: Select POST as the method since webhooks typically send data via POST requests.
    • Relative Path: Define a relative path for this resource. For example: /receive.
  5. In the resource, add your script logic.
  6. Ensure that the assigned user roles have the necessary permissions to execute this API.
  7. Go to System Web Services > REST API Access and configure the access controls for your API.
  8. Get the Endpoint URL: The URL for your webhook endpoint will be in the format: https://.service-now.com/api/<base_api_path>/<relative_path>
    Example URL: If your instance is named dev12345, and you used /api/webhook as the base path and /receive as the resource path, the URL would be: https://dev12345.service-now.com/api/webhook/receive

Using Salesforce

To set up your endpoint with Salesforce, use the following steps:

  1. Go to your Salesforce instance and log in.
  2. Navigate to Setup > Apex Classes.
  3. To create a new Apex class, click on New and create an Apex class, for example:

    ```java
@RestResource(urlMapping='/webhook/*')
global with sharing class WebhookReceiver {
    @HttpPost
    global static void doPost() {
        RestRequest req = RestContext.request;
        RestResponse res = RestContext.response;
        // Process the incoming request
        String requestBody = req.requestBody.toString();
        // Add your custom logic to handle the webhook payload
        System.debug('Received webhook: ' + requestBody);
        res.responseBody = Blob.valueOf('Webhook received');
        res.statusCode = 200;
    }
}
```
  4. (Optional) Set up a Salesforce site: If you want the webhook to be accessible from the internet without requiring authentication, you need to set up a Salesforce site.
  5. Navigate to Setup > Sites and click New, following the steps to create a new site and ensuring that the site is active. To set up the site, configure the site settings (including the URL) and ensure that the necessary Apex class is accessible by the guest user profile.
  6. To set guest user permissions, navigate to Setup > Sites, click on the name of your site, then click on Public Access Settings.
  7. In the profile, add permissions for the WebhookReceiver Apex class. Click Enabled Apex Class Access. Add the WebhookReceiver class to the enabled list.
  8. Get the URL: The URL for your webhook endpoint will be in the format: https://.force.com/services/apexrest/webhook/
    Note: Replace ` with the actual name of your Salesforce site.

Using Postman

To set up your endpoint with Postman, use the following steps:

  1. Go to your Postman account and log in.
  2. To create a new Mock Server, navigate to New in the top left corner and select Mock Server.
    • Select Collection: Choose an existing collection or create a new one.
    • Add a Mock Server: Click Add Example and give the example a name (for example: "Webhook Request").
    • Define URL Path: Set the request type to POST and define a path for the webhook (for example: /webhook).
    • Save and Mock Server URL: Save the example and note the mock server URL provided by Postman. This URL will be used to receive the webhooks.To navigate to Postman Flows in Postman, select the Flows tab. If it is not already visible, the Flows feature must be enabled.
  3. To create a new flow, click New Flow and name your flow (for example: Webhook Flow).
  4. Add a Request Block by dragging and dropping a Request block onto the canvas.
    • Method: Set it to POST.
    • URL: Use the mock server URL you created earlier (e.g., https://<mock_server_id>.mock.pstmn.io/webhook).
    • Body: You can define the expected body schema here.
  5. To add a Test Block, drag and drop a Test block after the Request block to process the incoming webhook data.
    • Script: Add JavaScript to process the incoming data. Here's an example script that logs the webhook payload:
let webhookData = pm.request.body.raw;
console.log('Received webhook payload:', webhookData);
// Add your custom processing logic here
  1. Connect Blocks: Ensure that the Request block is connected to the Test block.
  2. Click Save to save your flow.
  3. Get the URL: The URL for your webhook will be the mock server URL you noted earlier (e.g., https://<mock_server_id>.mock.pstmn.io/webhook). If your mock server ID is 123456, the URL would be: https://123456.mock.pstmn.io/webhook

3. Integrate with Your Source System UKG Webhooks

Now, you need to tell your UKG Webhooks subscription that will be sending the webhooks where to send them. This involves:

4. Test the Webhook

It’s important to make sure everything is set up correctly:

  • Trigger an Event: Perform an action that should trigger the webhook, see event catalog: UKG Webhooks Events Catalog or use the UKG Webhooks "Test an endpoint" feature: Test an endpoint
  • Check the Delivery: Go back to your chosen service and check if the webhook was received. The service should show the received data.

5. Monitor and Maintain

Once everything is set up:

  • Monitor the Webhooks: Regularly check to ensure that webhooks are being sent and received correctly.
  • Update as Needed: If you change services or need to update the URL, repeat the steps above.

Consuming the Webhook Payload

When a webhook is triggered, it sends data (payload) to your endpoint URL. Here’s how to handle that data:

1. Understanding the Payload

The payload is the data sent by the webhook. It usually contains information about the event that triggered the webhook. This data is typically in JSON format, which looks something like this:

{ 
  "EventId": 518577181, 
  "EventTime": "2024-06-03T17:38:57.397", 
  "EventType": "EmployeeAddressChangeEvent", 
  "Operation": "Update", 
  "Payload": { 
    "CoId": “YOUR_COMPANY_IDENTIFIER”, 
    "EeId": “YOUR_EMPLOYEE_IDENTIFIER”, 
    "IntegrationRecordId": null 
  }, 
  "Tenant": "YOUR_TENANT" 
}

2. Processing the Payload

You’ll need to set up a way to receive and process this data. Here’s a basic approach:

  • Server Setup: Set up a server to receive the webhook data. This could be a simple script running on a web server that listens for incoming requests at your endpoint URL.
  • Parse the Data: Write a script to parse the JSON payload. Extract the necessary information from the payload to use in your business logic.

3. Automate Business Processes

Once you have the payload data, you can use it to automate various business processes by making API calls or posting data to other SaaS providers. Here’s how:

Example: Using UKG API for retrieving Employee demographics

  1. Receive Webhook: Your server receives a webhook payload from UKG Webhooks for an employee address change event.
  2. Parse Payload: Extract relevant details like EeId, CoId from payload, US-Customer-API-Key From the headers.
  3. Get the change details for the Employee: Use UKG’s API to get the Employee demographic details that have changed. Employee Demographic API
import requests 

url = "https://YOUR_COMPANY_HOST/personnel/v1/employee-demographic-details?employeeId=YOUR_EMPLOYEE_IDENTIFIER&companyId=YOUR_COMPANY_IDENTIFIER” 

payload = {} 

headers = { 
 	'US-Customer-Api-Key': ‘YOUR_API_KEY’, 
	'Authorization': 'Basic YOUR_BASIC_AUTH’ 
}  

response = requests.request("GET", url, headers=headers, data=payload) 

print(response.text)
  1. Use the data from the API response: Using MS Team’s channel webhook URL to post a message in a specific channel with the employees changed data.
import requests 
import json 

# Get the endpoint URL from Teams channel > Manage Channel > Connectors > Incoming Webhook 
url = "https://your_company.webhook.office.com/webhookb2/0e14d875-7242-462e-ae19/IncomingWebhook/8afebe45bb64450bb3938f4c74/" 
payload = json.dumps({ 
    "personId": "{personId}",
    "employeeId": "{employeeId}",
    "companyId": "{companyId}",
    "addressLine1": "{addressLine1}",
    "addressLine2": "{addressLine2}",
    "addressLine3": "{addressLine3}",
    "addressLine4": "{addressLine4}",
    "addressCity": "{addressCity}",
    "addressState": "{addressState}",
    "addressZipCode": "{addressZipCode}",
    "addressCountry": "{addressCountry}",
    "addressCounty": "{addressCounty}"
}) 

headers = { 
  'Content-Type': 'application/json' 
} 

# Send employee adderess details from the response to my Teams Channel 
response = requests.request("POST", url, headers=headers, data=payload) 

print(response.text)

Updated 5 months ago