Comment on page
Webhooks
You can receive real-time status updates of your income verification requests by using webhooks.
You can receive notifications from Payscore via webhooks when the following occurs:
- When an applicant has begun an income verification request
- When an applicant successfully completes an income verification request
- When a screening group is completed successfully
- When an applicant's bank is not supported
- When an applicant does not have a bank
- When an applicant does not have online banking
- When an applicant cannot connect their bank
- When an applicant states that they share a bank, or do not produce any income
- This is only for income verification requests with multiple applicants'
- When an applicant re-opens their screening to modify the information
- When an income verification report is 2 days from expiring
- When an income verification report has expired
- When an incomplete income verification request has expired
- When an applicant consents to our Terms of Service and Privacy Policy
- When an applicant confirms that their income summary for a bank connection is accurate and complete
- When an applicant confirms that their aggregate income summary for multiple bank connections is accurate and complete
- When an applicant consents and confirms their final submission of their report
The webhook will be sent as a
POST request to the webhook_url attribute of the screening group you created.Payscore fires the
BEGIN_SCREENING webhook when an applicant signs up and begins the income verification request.Example:
{
"code": "BEGIN_SCREENING",
"screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
"screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
}
Once the applicant finishes an income verification process, the
SCREENING_COMPLETED webhook will fire. Note that this event fires when an individual income screening is completed, not the entire screening group.Example:
{
"code": "SCREENING_COMPLETED",
"screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
"screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
}
Once every applicant from the screening group has completed their income verification request, the
SCREENING_GROUP_COMPLETED webhook will fire. This means that the income verification report has been generated and is ready to be presented.This webhook might fire several times due to an applicant re-opening their screening 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 income report.
Example:
{
"code": "SCREENING_GROUP_COMPLETED",
"screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4"
}
If the applicant's bank is not supported, the
BANK_NOT_SUPPORTED webhook will fire. The applicant's bank will be in the value property.Example:
{
"code": "BANK_NOT_SUPPORTED",
"screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
"screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
"value": "Small Alaskan Credit Union"
}
If the applicant does not use online banking, the
NO_ONLINE_BANKING webhook will fire. The applicant's bank will be in the value property.Example:
{
"code": "NO_ONLINE_BANKING",
"screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
"screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
"value": "Small Alaskan Credit Union"
}
If the applicant does not have a bank, the
NO_BANK webhook will fire.Example:
{
"code": "NO_BANK",
"screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
"screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
}
If the applicant's bank cannot connect due to technical errors, the
BANK_CANNOT_CONNECT webhook will fire. The applicant's bank will be in the value property.Example:
{
"code": "BANK_CANNOT_CONNECT",
"screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
"screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
"value": "Small Alaskan Credit Union"
}
If the applicant states that they share a bank with another applicant, the
SHARE_BANK webhook will fire. This only occurs with screening groups with more than 1 applicant.
Example:{
"code": "SHARE_BANK",
"screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
"screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
}
If the applicant states that they produce no income, the
NO_INCOME webhook will fire. This only occurs with screening groups with more than 1 applicant.Example:
{
"code": "NO_INCOME",
"screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
"screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
}
If the applicant decides to re-open their screening request because they want to add or remove accounts or modify their income explanation, this webhook will fire. In this case, you will want to update the screening status back to
In Progress on your end until the SCREENING_COMPLETED webhook fires again.Example:
{
"code": "RE_OPEN_SCREENING",
"screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
"screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
}
Our reports expire in 14 days in order to remain FCRA compliant. Two days before the report expires, we will send a webhook providing the following notice:
REPORT_SOON_TO_EXPIRE.Example:
{
"code": "REPORT_SOON_TO_EXPIRE",
"screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4"
}
Our reports expire in 14 days in order to remain FCRA compliant. Once the report expires, we will send a webhook providing the following notice:
REPORT_EXPIRED.Example:
{
"code": "REPORT_EXPIRED",
"screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4"
}
If an invite has not been completed within 14 days, the invite expires for the applicant. When this happens, a webhook with the
INVITE_EXPIRED event will be sent, which includes the screening_id of the incomplete screening that expired.Example:
{
"code": "INVITE_EXPIRED",
"screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
"screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
}
This webhook is fired when the applicant consents to our Terms of Service and Privacy Policy on our first screen. The exact messaging that they consent to is:
I, {Applicant Name}, hereby consent to income verification screening at the request of {Decision Maker Display Name} and certify that I have read and agree to Payscore's
Terms of Service and Privacy Policy.
The value in the webhook is the unix timestamp of the action.
Example:
{
"code": "INITIAL_TOS_AND_PRIVACY_POLICY_CONSENT",
"screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
"screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
"value": 1693327958
}
Once an applicant connects a bank account, they are shown a copy of their income summary and are asked to confirm the accuracy and completeness of the income summary for the connected bank account. The exact messaging they consent to is:
I hereby certify that the income data provided above is accurate and complete or is made accurate andcomplete with the inclusion of any explanations I provide.
The value in the webhook is the unix timestamp of the action.
Example:
{
"code": "BANK_CONNECTION_ACCURACY_CONSENT",
"screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
"screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
"bank_connection_id": "91dc3940-5b2c-4da2-9cc8-6e6bb88be395",
"value": 1693327958
}
If the applicant connects more than one bank account, they are shown the aggregate income summary combining all bank accounts and are asked to confirm the accuracy and completeness of the aggregated income summary. This webhook will only fire when the applicant connects more than one bank account. The exact messaging that they consent to is:
I hereby certify that the income data provided above is accurate and complete or is made accurate andcomplete with the inclusion of any explanations I provide.
The value in the webhook is the unix timestamp of the action.
Example:
{
"code": "COMBINED_ACCOUNTS_ACCURACY_CONSENT",
"screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
"screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
"value": 1693327958
}
This webhook is fired when the applicant submits their income report. The applicant cannot submit their income report without accepting the following messaging:
The income report is accurate and complete and I release Payscore from any and all liability related to its accuracy and completeness as well as related to the use of the report by {Decision Maker Display Name} in assessing my application.
The value in the webhook is the unix timestamp of the action.
Example:
{
"code": "FINAL_ACCURACY_AND_COMPLETENESS_CONSENT",
"screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
"screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
"value": 1693327958
}
When a webhook is sent, Payscore uses the webhook body and your secret key to create a hash signature, which is sent in the header
Verification-Signature. The hash is created using HMAC-SHA256 and is hex encoded. In order for you to validate that the webhook is legitimate, hash the raw webhook body using your secret key as the key, and then compare your generated signature with the
Verification-Signature header value.Do Not Parse or Cast the Webhook Request Body
While generating the signature at your end, ensure that the webhook body passed as an argument is the raw webhook request body. Do not parse or cast the webhook request body.