# Webhooks

You can receive notifications from Payscore via webhooks when the following occurs:

* When an applicant has begun a verification request
* When an applicant successfully completes a verification request
* When a report is generated and ready to be viewed

The webhook will be sent as a `POST` request to the `webhook_url` attribute of the applicant group you created.

## `VERIFICATION_STARTED`

Payscore fires the `VERIFICATION_STARTED` webhook when an applicant begins the income verification request. This webhook does not fire more than once.

Example:

```json
{
    "code": "VERIFICATION_STARTED",
    "verification_id": "905963d4-0649-4046-8f39-7997a9e45ed4"
}
```

## `VERIFICATION_COMPLETED`

Once the applicant finishes a verification, the `VERIFICATION_COMPLETED` webhook will fire.

Example:

```json
{
    "code": "VERIFICATION_COMPLETED",
    "verification_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
    "reason_completed": "finished"
}
```

{% hint style="warning" %}
This webhook might fire several times due to an applicant re-opening their verification in order to add/remove an account or modify their explanation. Be sure to update your report whenever this webhook fires in order to show the most updated report.
{% endhint %}

## `REPORT_READY`

Once a report has been generated and ready to be viewed, the `REPORT_READY` webhook will fire. This is different from the `VERIFICATION_COMPLETED` webhook since some reports like the household income report require all applicants to complete the verification before a report is generated.

The `report_type` field will allow you to determine which type of report to expect when fetching the report's PDF or JSON data. Values can be `income`, `asset` , or `identity` .

For reports for individual applicants (such as identity verification reports), the `applicant_id` field will be present to allow you to correlate the report to the individual applicant. Household reports like `income` will be correlated to the entire applicant group.

The `report_id` will be used for you to fetch the report data.

Example:

```json
{
    "code": "REPORT_READY",
    "applicant_group_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
    "applicant_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
    "report_id": "2d376488-fc60-4193-bac2-1023764b7842",
    "report_type": "income"
}
```


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.payscore.com/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.