> For the complete documentation index, see [llms.txt](https://docs.payscore.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payscore.com/payscore-v1-deprecated/sending-income-verification-requests/webhooks.md). # 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 is added to a screening group * When an applicant is removed from a screening group The webhook will be sent as a `POST` request to the `webhook_url` attribute of the screening group you created. ### `BEGIN_SCREENING` 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" } ``` ### `SCREENING_COMPLETED` 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" } ``` ### `SCREENING_GROUP_COMPLETED` 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. {% hint style="warning" %} 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. {% endhint %} Example: ``` { "code": "SCREENING_GROUP_COMPLETED", "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4" } ``` ### `BANK_NOT_SUPPORTED` 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" } ``` ### `NO_ONLINE_BANKING` 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" } ``` ### `NO_BANK` 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" } ``` ### `BANK_CANNOT_CONNECT` 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" } ``` ### **`SHARE_BANK`** 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" } ``` ### `NO_INCOME` 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" } ``` ### `RE_OPEN_SCREENING` 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" } ``` ### **`REPORT_SOON_TO_EXPIRE`** 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" } ``` ### **`REPORT_EXPIRED`** 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" } ``` ### **`INVITE_EXPIRED`** 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" } ``` ### **`APPLICANT_ADDED`** If an applicant is added to a screening group after it has been created, the `APPLICANT_ADDED` webhook will fire. The added applicant’s first name, last name, email address and phone number will be in the value property. Note that the phone number field may be null if no applicant phone number is provided. Example: ``` { "code": "APPLICANT_ADDED", "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4", "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562", "value": { "applicant_first_name": "John", "applicant_last_name": "Smith", "applicant_email": "john@gmail.com", "applicant_phone_number": "+18001234567" } } ``` ### **`APPLICANT_REMOVED`** If an applicant is removed from a screening group after it has been created, the `APPLICANT_REMOVED` webhook will fire. The removed applicant’s first name, last name, email address and phone number will be in the value property. Note that the phone number field may be null if no applicant phone number is provided. Example: ``` { "code": "APPLICANT_REMOVED", "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4", "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562", "value": { "applicant_first_name": "John", "applicant_last_name": "Smith", "applicant_email": "john@gmail.com", "applicant_phone_number": "+18001234567" } } ``` ### Validating Webhooks 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. {% hint style="warning" %} **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. {% endhint %} --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.payscore.com/payscore-v1-deprecated/sending-income-verification-requests/webhooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.