Working with webhooks

New to webhooks? This guide covers everything you need to get started.

What is a webhook?

Whenever something noteworthy happens — a new request comes in, or a status changes — PeopleCheck pushes a message to a URL you specify. That way, you don’t have to repeatedly query our endpoints or check the dashboard yourself to stay current.

Benefits of using webhooks

Real-time visibility: Find out about changes as soon as they occur.
Workflow automation: Kick off processes automatically as soon as new data comes in.
Less overhead: Skip the manual polling and let updates reach you directly.

The mechanics of webhooks

Whenever a candidate fills out their onboarding form, a check element wraps up, or a screening changes status, PeopleCheck fires off a notification to your configured endpoint. Each notification is delivered as an HTTP POST request carrying the event’s data, so your systems can respond without manual intervention.

Common scenarios

New requests: Keep your systems synced by automatically capturing incoming candidate requests.
Status changes: Be alerted as soon as a screening’s status shifts, so your team can respond right away.
Workflow triggers: Use any event to kick off internal automations — like firing off an email or updating a record in your HRIS.

Reading a webhook notification

Every notification is a JSON body with two top-level fields:

event — which of the event types just happened in your PeopleCheck backoffice.
data — the details of that event. Rather than a fixed, webhook-only shape, data is exactly the same payload returned by the REST endpoint tied to that event — see the Payload matches column below.

Since the shapes are shared, any parsing logic you’ve already built around the REST responses can be reused as-is when handling webhook notifications.

Event types

Event	When it fires	Payload matches
`REQUESTED`	A new check request was created and the candidate was notified.	Create a request (`POST /requests`)
`IN_PROGRESS`	The candidate finished their onboarding form and the screening is now underway.	Screening overview (`GET /screenings/{id}`)
`ELEMENT_COMPLETED`	A single check element has wrapped up.	The matching result endpoint for that element (`GET /screenings/{id}/{element}`)
`COMPLETED`	The screening wrapped up with no adverse findings.	Screening overview (`GET /screenings/{id}`)
`COMPLETED_WITH_ALERT`	The screening wrapped up, but there are findings that need your review.	Screening overview (`GET /screenings/{id}`)
`UNABLE_TO_VERIFY`	The screening couldn’t be completed because information was missing or invalid.	Screening overview (`GET /screenings/{id}`)
`CANCELLED`	The request or screening was called off.	Screening overview (`GET /screenings/{id}`)

The status and progress.status values found in the payload correspond to the same screening statuses covered in Managing results.

Example payloads

{
  "event": "REQUESTED",
  "data": {
    "id": 4177,
    "name": "David Smith",
    "email": "david.smith@domain.com",
    "package": {
      "id": 20,
      "name": "3 years Background Check"
    },
    "token": "b2c185974fe2b3c79a0cc82efe784e80",
    "primaryCode": "PCB20XXXX",
    "secondaryCode": "Project-1",
    "count": 1,
    "created": "2022-09-23T01:15:13.000Z",
    "updated": "2022-09-23T01:15:13.000Z",
    "message": "Invite successfully sent"
  }
}

{
  "event": "ELEMENT_COMPLETED",
  "data": {
    "type": "Alias",
    "uri": "https://api.peoplecheck.com/screenings/54687/alias",
    "result": {
      "value": "unlisted",
      "status": "confirmed",
      "completed": "2023-04-04T13:50:25.000Z",
      "comment": null
    }
  }
}

{
  "event": "COMPLETED",
  "data": {
    "id": 54687,
    "name": "Jhon Smith",
    "email": "jhon.smith@testing.com",
    "birthDay": "1988-10-02T03:00:00.000Z",
    "primaryCode": "XXX89752",
    "secondaryCode": "TTTHT1",
    "documents": 3,
    "package": {
      "id": 4028,
      "name": "Pre-Hire Clearance"
    },
    "progress": {
      "total": 100,
      "status": "no_risk"
    },
    "timeline": [
      {
        "title": "Check element completed",
        "description": "Right to work (visa and work permits)",
        "summary": "Completed",
        "date": "2023-04-04T13:50:25.000Z"
      },
      {
        "title": "New check request",
        "description": "Pre-Hire Clearance",
        "summary": "Requested by: David Runner",
        "date": "2023-04-04T13:33:31.000Z"
      }
    ],
    "created": "2023-04-04T13:47:46.000Z",
    "completed": "2023-04-05T09:12:03.000Z"
  }
}

The COMPLETED example above also represents the shape you’ll get for IN_PROGRESS, COMPLETED_WITH_ALERT, UNABLE_TO_VERIFY, and CANCELLED — only progress.status (and completed) change to reflect the screening’s new state.

For ELEMENT_COMPLETED, the type and uri fields tell you which element just finished and where to fetch it directly — the same pair of fields returned in each components entry of a Screening overview. The result object itself is identical to what that element’s own endpoint (like Alias) returns.

Confirming notification authenticity

When you set a token while creating the webhook, that token gets sent along with every notification in the Authorization header as a Bearer token. Check this token on your server so you can confirm each request truly originated from PeopleCheck before you act on it.

Authorization header

Authorization: Bearer YOUR_WEBHOOK_TOKEN

Give it a try

Visit Create a new webhook to set one up. Once in place, you’ll see how webhooks save you time while keeping your team in the loop and ready to act.

Get Started

API Essentials

Packages

Requests

Results

Webhooks

Working with webhooks

What is a webhook?

Benefits of using webhooks

The mechanics of webhooks

Common scenarios

Reading a webhook notification

Event types

Example payloads

Confirming notification authenticity

Give it a try

​What is a webhook?

​Benefits of using webhooks

​The mechanics of webhooks

​Common scenarios

​Reading a webhook notification

​Event types

​Example payloads

​Confirming notification authenticity

​Give it a try

What is a webhook?

Benefits of using webhooks

The mechanics of webhooks

Common scenarios

Reading a webhook notification

Event types

Example payloads

Confirming notification authenticity

Give it a try