Documentation
What's NewUKG.comMarketplaceUKG Pro status

Webhook Triggers

ProHCMEventTrigger and UkgWebhookTrigger for event-driven and webhook-based workflows.

Webhook Triggers

Note: Compose is only available for Beta testing. See Welcome to UKG Compose > Beta Disclosure for more information.

Webhook triggers start workflows when an external system sends an HTTP request to a webhook endpoint. This page uses the same terminology you see in the editor (trigger, workflow, execution, test URL, production URL, Respond to Webhook, etc.).

UKG Compose provides two webhook trigger nodes: ProHCMEventTrigger for supported UKG Pro HCM events, and UkgWebhookTrigger for general UKG webhook entry points.

Webhook trigger nodes in UKG Compose

  • ProHCMEventTrigger - Start workflows from supported UKG Pro HCM events with event-specific payload handling
  • UkgWebhookTrigger - Provide general UKG webhook entry points with flexible HTTP method support and tenant-aware routing

Use webhook triggers when:

  • A UKG service needs to start a workflow from an event
  • Another system needs to call a workflow endpoint directly
  • The workflow should react in near real time to external requests
  • A business process needs a request-driven or event-driven entry point

When to use ProHCMEventTrigger

Use ProHCMEventTrigger when the workflow should start from a supported UKG Pro HCM event.

This trigger is the best fit when:

  • The source of truth is Pro HCM
  • The workflow should react to a defined Pro HCM business event
  • The goal is near-real-time automation tied to employee or workflow changes
  • The workflow should begin from an event subscription rather than a general-purpose webhook endpoint

Typical scenarios include:

  • Employee status change workflows
  • Onboarding or offboarding automation
  • Workflow completion follow-up
  • Real-time synchronization after Pro HCM changes

When to use UkgWebhookTrigger

Use UkgWebhookTrigger when the workflow needs a more general-purpose UKG webhook entry point.

This trigger is the best fit when:

  • Multiple UKG services or custom UKG-aligned integrations may call the endpoint
  • The workflow needs more flexibility around HTTP methods
  • Tenant-aware routing is required
  • Transaction or correlation tracking is important
  • The webhook is being used as a general integration entry point rather than only a Pro HCM event subscription

Typical scenarios include:

  • Multi-tenant webhook routing
  • Authenticated UKG service callbacks
  • Cross-system event synchronization
  • REST-like webhook endpoints for UKG-related operations

Choosing between the two triggers

Use one of these two simplified decision models:

Choose ProHCMEventTrigger when:

  • The event originates from Pro HCM
  • You want a Pro HCM-specific event entry point
  • The workflow is built around supported Pro HCM event subscriptions
  • The payload and response behavior are tied to Pro HCM event processing

Choose UkgWebhookTrigger when:

  • The workflow needs a broader UKG webhook receiver
  • The source may be another UKG service or integration layer
  • The workflow depends on HTTP method flexibility
  • Tenant validation or transaction tracking is part of the design
  • The workflow should expose a more general UKG-facing webhook endpoint

Common trigger concepts

Test URL and production URL

Webhook trigger nodes expose both a test URL and a production URL.

Use the test URL while building and validating the workflow.

Use the production URL after the workflow is activated and ready for live traffic.

This is one of the most important operational patterns for webhook-based workflows:

  • Build and validate with the test URL
  • Activate the workflow
  • Move the source system to the production URL

HTTP method

Webhook-based workflows may depend on the correct HTTP method.

Depending on the trigger and the source system, the workflow may expect:

  • POST
  • GET
  • PUT
  • PATCH
  • DELETE
  • other supported methods when relevant

The HTTP method configured in the trigger should match what the calling system is expected to send.

Path

Some webhook workflows use a default generated path, while others use a custom path for readability or routing.

Use a custom path when:

  • The endpoint needs a more meaningful name
  • The integration design benefits from clearer routing
  • The workflow is part of a broader service pattern

In some designs, dynamic path segments may also be used when the workflow needs route parameters.

Response mode and synchronous workflows

Webhook triggers support two main response patterns:

Asynchronous (immediate acknowledgment):

  • The workflow acknowledges the request immediately
  • Processing continues in the background
  • The calling system receives a quick acknowledgment but not the workflow result
  • Best when the workflow may take time to complete or doesn't need to return data to the caller

Synchronous (controlled response):

  • The workflow processes logic and returns a structured response using Respond to Webhook
  • The calling system waits for and receives the workflow result
  • Best when the calling system expects specific response data, status codes, or headers
  • Creates an API-like or app-like request/response experience

Using Respond to Webhook for synchronous patterns

When a workflow needs to return data to the caller, use the Respond to Webhook node:

  1. Webhook trigger receives the request.
  2. Workflow processes business logic, queries data, or evaluates conditions.
  3. Respond to Webhook returns a structured response with:
    • HTTP status code (200, 400, 404, 500, etc.)
    • Response body (JSON, text, or other format)
    • Custom headers if needed
  4. The calling system receives the response and can use the returned data.

Important: In synchronous workflows, place Respond to Webhook at the point where you want to return the response. Nodes after Respond to Webhook will still execute, but the caller will have already received the response.

Choosing between asynchronous and synchronous patterns

Choose asynchronous when:

  • The workflow may take significant time to complete
  • The calling system only needs acknowledgment, not results
  • Heavy processing should happen in the background
  • The workflow includes approval wait states or multi-step processing

Choose synchronous when:

  • The calling system expects immediate data or status
  • The workflow acts as an API endpoint
  • Response time is fast enough for request/response interaction
  • The caller needs specific information to proceed with its own logic

Security and prerequisite considerations

Webhook-based workflows should be treated as externally reachable entry points and designed accordingly.

Security expectations

For webhook-based workflows, builders and admins should consider:

  • HTTPS-only production use
  • Access restrictions where supported
  • Authentication requirements when applicable
  • Validation of the calling source
  • Review of execution history for failed or unexpected requests

ProHCMEventTrigger considerations

For ProHCMEventTrigger, typical security and readiness considerations include:

  • Pro HCM webhook configuration
  • Webhook accessibility from UKG systems
  • Secure webhook handling
  • (Optional) Controls such as source restrictions or authenticity validation where supported

UkgWebhookTrigger considerations

For UkgWebhookTrigger, typical security and readiness considerations include:

  • Matching the expected HTTP method
  • Header-based identity or tenant validation when needed
  • Bearer token or similar authentication patterns when required
  • Transaction or correlation IDs for tracking and idempotency
  • Careful design of request/response behavior

Common workflow patterns

Pro HCM event to notification or downstream action

Pattern:

  1. ProHCMEventTrigger.
  2. IF or Switch to inspect event type or payload.
  3. Notification (see Notification Nodes), data update (see API Integration Nodes), or downstream action node.

Use this pattern when the workflow should react differently to different Pro HCM event conditions.

Webhook trigger to routing and orchestration

Pattern:

  1. UkgWebhookTrigger.
  2. Set, IF, or Switch to inspect the request.
  3. One or more UKG or third-party action nodes.

Use this pattern when the webhook is acting as a general integration entry point.

Synchronous request/response with Respond to Webhook

Pattern:

  1. UkgWebhookTrigger or webhook trigger receives request.
  2. Extract and validate request data.
  3. Apply business logic, query data, or evaluate conditions.
  4. Respond to Webhook with status code, response body, and headers.
  5. Optional: Continue with background processing after response is sent.

Example scenarios:

  • API endpoint: External system calls workflow, receives JSON response with validation results
  • Data lookup: Caller sends identifier, workflow queries data and returns enriched result
  • Validation service: Caller sends request, workflow validates against rules and returns pass/fail with details
  • Synchronous integration: Partner system expects immediate confirmation or transaction response

This pattern is essential when the workflow must act like an API rather than an asynchronous background process.

Webhook trigger to asynchronous downstream work

Pattern:

  1. Webhook trigger.
  2. Quick validation or acknowledgment.
  3. Downstream processing in later nodes or related workflow paths.

Use this pattern when the inbound webhook should be acknowledged quickly and the heavier work can happen after the initial response behavior is satisfied.

Tips for working with webhook triggers

  • Use the same terminology the editor uses, especially around test URL, production URL, response mode, and Respond to Webhook
  • Test with the test URL first, then update the source system to the production URL only after activation
  • For asynchronous workflows: keep the initial webhook handling path lightweight when the workflow may take time to finish
  • For synchronous workflows: ensure response time is fast enough by keeping logic before Respond to Webhook efficient
  • Match the configured HTTP method (POST, GET, PUT, etc.) to what the calling system actually sends
  • Use IF or Switch to separate different event types, tenants, or routing conditions
  • Use Respond to Webhook when the caller expects specific response data, not just acknowledgment
  • Review Execution History after every webhook test to confirm the payload, trigger behavior, and downstream path
  • For broader integration patterns, use transaction or correlation identifiers when available
  • Design for duplicate requests when the calling system may retry on timeout
  • Webhook endpoints in Compose are secured within UKG Cloud, but validate prerequisites and source expectations before production use

Common pitfalls to avoid

  • Testing with the test URL and forgetting to switch the source system to the production URL
  • Activating the workflow without validating the trigger configuration first
  • Using the wrong HTTP method
  • Assuming the request payload contains fields that were not actually sent
  • Performing too much work in the initial webhook handling path
  • Not designing for duplicate or repeated requests when the source system may retry
  • Not checking Pending or Failed executions during troubleshooting

Troubleshooting webhook trigger issues

When a webhook-triggered workflow does not behave as expected, start by checking if:

  • The workflow is active
  • The correct URL was used
  • The correct HTTP method was used
  • The expected source system actually sent the request
  • The execution appears in Execution History
  • The workflow acknowledged the request as expected
  • The payload contained the expected values
  • The downstream nodes failed after the trigger succeeded

For operational troubleshooting patterns, use the Administration and Operations page together with this one.

Related nodes and workflow patterns

Webhook triggers are commonly used with:

  • IF for conditional routing
  • Switch for routing by event type or tenant
  • Set for extracting and normalizing incoming data
  • Respond to Webhook when a custom response is needed
  • Error Trigger for handling downstream failures
  • Notification nodes for alerting or approval-style follow-up
  • Query and action nodes for enrichment and business processing

Related pages

Other node types:

Conceptual pages:

Updated 8 days ago