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:

{
    "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:

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

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.

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:

{
    "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"
}