> 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/entity-results/retrieving-entity-verification-results/setting-up-a-webhook.md).

# Setting up a webhook

Instead of retrieving verification results, you can use a webhook that sends results automatically.

Rather than manually retrieving results using the [Retrieving entity verification results](https://manual.personr.co/api-documentation/entity-results/retrieving-entity-verification-results.md) endpoint, you can set up a webhook that sends the verification status and data to your API once a verification has finished processing.

Providing us your endpoint URL is easy. Simply head to <https://enterprise.personr.co/dashboard/dev-space> and click on Webhooks.

Enter your API endpoint that's listening, and hit Save.

<figure><img src="https://2927352434-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyAmEVMxhOOdXgxn7sjnz%2Fuploads%2FIqZoJbMXSJDRkhTz1Gqz%2FScreenshot%202024-02-28%20at%2012.28.43%E2%80%AFpm.png?alt=media&amp;token=5571b80b-0cb7-424a-b9ae-9340357d7464" alt=""><figcaption></figcaption></figure>

Be sure to generate a webhook authentication token, and only accept authenticated calls from us. We'll send a POST request to your endpoint, with your generated token in the header.

#### Webhook Response

```json
{
  "applicantId": "140000249274x80293840283",
  "status": "Reviewed",
  "reviewAnswer": "Rejected",
  "rejectLabel": "SANCTIONS, COMPROMISED_PERSONS",
  "entityType": "AUSTRALIAN PROPRIETARY COMPANY, LIMITED BY SHARES",
  "registrySource": "AUSTRALIAN SECURITIES & INVESTMENTS COMMISSION",
  "registeredAddress": "123 EXAMPLE LANE, PERTH, 6000, WA, AUSTRALIA",
  "companyName": "EXAMPLE LTD",
  "registrationNumber": "123 456 789",
  "incorporatedOn": "2020-12-01",
  "representativeEmail": "example@personr.co",
  "representativePhone": "0400 000 000",
  "flowQuestions": "Example Question 1, Example Question 2",
  "flowAnswers": "Entity Answer 1, Entity Answer 2",
  "flow": "KYB Basic",
  "sourceKey": "Example Source Key",
  "externalUserId": "[\"user_123\"]",
  "trustDeedStatus": "not_required",
  "deedRequired": "false"
}
```

{% hint style="warning" %}
Every value in the webhook is sent as text (or `null` when empty). This differs from the [Retrieving entity verification results](https://manual.personr.co/api-documentation/entity-results/retrieving-entity-verification-results.md) endpoint, which returns lists as arrays.
{% endhint %}

| Field                           | In the webhook                                                                 | From the status endpoint            |
| ------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------- |
| `rejectLabel`                   | One string. Several labels are comma-separated, e.g. `"SANCTIONS, WATCHLIST"`. | `rejectLabels`, an array of strings |
| `flowQuestions` / `flowAnswers` | One comma-separated string                                                     | `flowAnswers`, an array             |
| `externalUserId`                | A JSON-encoded string, e.g. `"[\"user_123\"]"`. Parse it to get the array.     | An array of strings                 |
| `deedRequired`                  | The text `"true"` or `"false"`                                                 | A boolean                           |

Registry fields (`entityType`, `registeredAddress`, `incorporatedOn`) are `null` when no registry check has run, for example when an entity is manually reviewed straight after it is created.

`trustDeedStatus` and `deedRequired` show whether the entity needs a trust deed to complete due diligence. See [Retrieving entity verification results](https://manual.personr.co/api-documentation/entity-results/retrieving-entity-verification-results.md) for the values. The webhook is sent when the result is ready, which is usually before a deed has been uploaded, so call the status endpoint later to check whether the deed has since been confirmed.

## Delivery and retries

We send each webhook as a POST with a JSON body (`Content-Type: application/json`). Respond with any 2xx status within a few seconds, and process the event asynchronously if you need longer.

If your endpoint returns a non-2xx status or doesn't respond, we retry up to 5 times:

| Attempt | Sent                       |
| ------- | -------------------------- |
| 1       | When the event happens     |
| 2       | 1 minute after attempt 1   |
| 3       | 5 minutes after attempt 2  |
| 4       | 30 minutes after attempt 3 |
| 5       | 2 hours after attempt 4    |
| 6       | 12 hours after attempt 5   |

Each retry carries the current state of the record, so treat webhooks as notifications and de-duplicate on `applicantId` (and `event`, where present). Once a delivery succeeds, no further retries are sent. If a webhook still fails after the last retry, call the [Retrieving entity verification results](https://manual.personr.co/api-documentation/entity-results/retrieving-entity-verification-results.md) endpoint to catch up.

The same delivery and retry rules apply to the ownership-ready and onboarding webhooks.


---

# 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/entity-results/retrieving-entity-verification-results/setting-up-a-webhook.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.
