> For the complete documentation index, see [llms.txt](https://manual.personr.co/api-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manual.personr.co/api-documentation/applicant-results/retrieving-applicant-verification-results/setting-up-a-webhook/onboarding-webhooks.md).

# Onboarding webhooks

Get notified when an applicant opens their link, or opens it and doesn't finish.

As well as the result webhook, Personr can notify you while an applicant is still onboarding:

| Event                   | Sent when                                                               |
| ----------------------- | ----------------------------------------------------------------------- |
| `onboarding.opened`     | The applicant opens their verification link for the first time          |
| `onboarding.incomplete` | The applicant opened their link but submitted nothing within 60 minutes |

These use the same endpoint URL and authentication token as your [result webhook](https://manual.personr.co/api-documentation/applicant-results/retrieving-applicant-verification-results/setting-up-a-webhook.md).

## Turning them on

Onboarding webhooks are **off by default**, so existing integrations aren't affected.

1. Go to [Dev Space → Webhooks](https://enterprise.personr.co/dashboard/dev-space?navigation=Webhooks).
2. Make sure your endpoint URL is saved.
3. Under **Advanced**, switch on **Also send onboarding events**.

The change applies from the next link an applicant opens. Switch it off at any time to stop them.

{% hint style="warning" %}
Before switching them on, make sure your endpoint handles both kinds of webhook. Onboarding webhooks have an `event` field and no `actionStatus`, so check `event` first and only treat a webhook as a verification result when `event` is missing.
{% endhint %}

#### Webhook payload

```json
{
  "event": "onboarding.incomplete",
  "applicantId": "4242424242424x424242424242424242",
  "linkId": "4343434343434x434343434343434343",
  "onboardingStatus": "Incomplete",
  "openedAt": "2026-10-26T04:06:00.883Z",
  "sentAt": "2026-10-26T05:06:01.120Z"
}
```

| Field              | Description                                                           |
| ------------------ | --------------------------------------------------------------------- |
| `event`            | `onboarding.opened` or `onboarding.incomplete`                        |
| `applicantId`      | The applicant                                                         |
| `linkId`           | The onboarding link that was opened                                   |
| `onboardingStatus` | The link's status when the webhook was sent: `Opened` or `Incomplete` |
| `openedAt`         | When the link was first opened (ISO 8601)                             |
| `sentAt`           | When this webhook was sent (ISO 8601)                                 |

If an applicant finishes after an `onboarding.incomplete`, you'll receive the normal result webhook when their verification is processed. To check the current state at any time, use [Checking onboarding link status](https://manual.personr.co/api-documentation/applicant-results/checking-onboarding-link-status.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://manual.personr.co/api-documentation/applicant-results/retrieving-applicant-verification-results/setting-up-a-webhook/onboarding-webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
