We’re implementing automated onboarding provisioning and running into callback endpoint failures. When the onboarding process completes in UKG Pro 2022.2, our webhook should receive a callback with candidate details, but we’re consistently getting 400 Bad Request responses.
Using Postman to test the callback structure, I noticed the header validation seems strict. The error message mentions missing required headers, but the API documentation doesn’t clearly specify which headers are mandatory beyond Authorization.
Our callback endpoint requirements include handling candidate data for automated provisioning into downstream systems (email creation, access provisioning, equipment ordering). The 400 errors are blocking our entire automation workflow.
Has anyone successfully configured onboarding completion callbacks? What specific headers does UKG Pro expect in the callback request?
The Candidate-ID header is definitely required for onboarding callbacks. I ran into this exact issue last year. UKG Pro sends callbacks with specific custom headers that your endpoint needs to accept and validate. Beyond the standard Authorization header, you need to handle X-UKG-Candidate-ID, X-UKG-Event-Type, and X-UKG-Timestamp. The 400 error you’re seeing is likely because your endpoint isn’t configured to accept these custom headers, or your Postman test isn’t including them in the request simulation.
The X-UKG-Event-Type header uses specific values: ONBOARDING_STARTED, ONBOARDING_COMPLETED, ONBOARDING_CANCELLED. For your use case, you want ONBOARDING_COMPLETED. The X-UKG-Candidate-ID is a GUID format (UUID v4). One thing to watch - if your callback endpoint takes more than 5 seconds to respond, UKG Pro will timeout and retry, which can cause duplicate processing issues in your automation. Make sure your endpoint responds with 200 OK immediately and processes asynchronously.
I’ve seen similar callback issues with onboarding workflows. The 400 errors usually indicate header problems, but UKG’s error messages aren’t always specific about what’s missing. Have you checked if your endpoint is sending back the correct Content-Type header? Also, verify that your callback URL is registered correctly in the UKG Pro webhook configuration - sometimes the registration includes specific header expectations that aren’t in the standard docs.
Thanks Alex - that’s helpful context. I checked our endpoint configuration and we’re only validating the Authorization header. Are there specific formats or validation rules for X-UKG-Candidate-ID? Also, does the X-UKG-Event-Type header use specific enum values, or is it free text? Our automated provisioning system needs to parse these reliably to trigger the right downstream workflows.