Webhooks

The Closing Docs

Search…

The Closing Docs

Introduction

Authentication

Sending Income Verification Requests

Creating a Screening Group

Receiving Status Updates

Webhooks

Resend Screening Request Notification

Force-Complete a Screening Group Request

Delete a Screening Group

Reports

Getting the Report Url

Getting the Report Data

Using Demo Bank Data

Webhooks

You can receive real-time status updates of your income verification requests by using webhooks.

You can receive notifications from The Closing Docs 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 or 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 a income verification report is 2 days from expiring
When a income verification report has expired
The webhook will be sent as a POST request to the webhook_url attribute of the screening group you created.
BEGIN_SCREENING
The Closing Docs fires the BEGIN_SCREENING webhook when an applicant signs up and begins the AIV screening.
Example:
1
{
2
    "code": "BEGIN_SCREENING",
3
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
4
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
5
}
Copied!
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:
1
{
2
    "code": "SCREENING_COMPLETED",
3
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
4
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
5
}
Copied!
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.
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:
1
{
2
    "code": "SCREENING_GROUP_COMPLETED",
3
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4"
4
}
Copied!
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:
1
{
2
    "code": "BANK_NOT_SUPPORTED",
3
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
4
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
5
    "value": "Small Alaskan Credit Union"
6
}
Copied!
NO_BANK
If the applicant does not have a bank or use online banking, the NO_BANK webhook will fire.
Example:
1
{
2
    "code": "NO_BANK",
3
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
4
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
5
}
Copied!
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:
1
{
2
    "code": "BANK_CANNOT_CONNECT",
3
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
4
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
5
    "value": "Small Alaskan Credit Union"
6
}
Copied!
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:
1
{
2
    "code": "SHARE_BANK",
3
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
4
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
5
}
Copied!
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:
1
{
2
    "code": "NO_INCOME",
3
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
4
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
5
}
Copied!
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:
1
{
2
    "code": "RE_OPEN_SCREENING",
3
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
4
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
5
}
Copied!
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:
1
{
2
    "code": "REPORT_SOON_TO_EXPIRE",
3
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4"
4
}
Copied!
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:
1
{
2
    "code": "REPORT_EXPIRED",
3
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4"
4
}
Copied!
Validating Webhooks
When a webhook is sent, The Closing Docs 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.