If you’re unfamiliar with webhooks, this guide will walk you through the essentials.

​
What are webhooks?

When important changes happen — like a new request or a status update — PeopleCheck sends a notification to a web address you choose. This means you don’t need to keep checking the system manually or poll our endpoints for updates.

​
Why use webhooks?

  • Instant updates: Get notified the moment something changes.
  • Automation: Trigger workflows automatically when new data arrives.
  • Efficiency: Stop polling for updates and let the information come to you.

​
How webhooks work

When a candidate submits their onboarding form, a check element completes, or a screening’s status changes, PeopleCheck sends a notification to the URL you’ve configured. These notifications are HTTP POST requests that contain data about the event, allowing your systems to react automatically.

​
Example use cases

  • New requests: Automatically capture new candidate requests to keep your systems up to date.
  • Status updates: Get notified when a screening’s status changes, so your team can take immediate action.
  • Automated workflows: Trigger internal workflows whenever a specific event occurs — such as sending an email or updating a record in your HRIS.

​
Understanding webhook notifications

Webhook notifications are sent as JSON payloads to your specified URL. Each payload contains the relevant details of the event that triggered it, so you can integrate seamlessly with your existing systems.
Payload
In this example:
  • The event field tells you what kind of update occurred — here, a new request was created.
  • The data object contains the specifics of the event, including the request id, the current status, the package, and the candidate’s details.

​
Event types

The status values in the payload mirror the screening statuses described in Managing results.

​
Verifying notifications

If you set a token when creating the webhook, it is sent on every notification in the Authorization header as a Bearer token. Validate this token on your server to confirm each request genuinely came from PeopleCheck before acting on it.
Authorization header

​
Try it yourself

Head over to Create a new webhook. You’ll find that integrating webhooks not only saves time, but also keeps your team informed and proactive.