AccountChek Webhook Postbacks

When creating an AccountChek Order request for a borrower, it’s important to be able to receive notifications regarding both where the borrower is in the process, as well as when the Borrower’s reports are available. To allow for this, we provide the ability to set up a self-hosted application for receiving and handling postbacks from the AccountChek Webhook.

This method of handling status updates should be used in conjunction with use of the API call to check the status of the service (VOA status and VOIE status) to avoid a single point of failure.

Note: the VOIE service webhooks require opting in to receive them. To opt in, please reach out to AccountChek support.

1. The Requirements
2. What You Will Receive Back
   • VOA
   • VOIE
3. Troubleshooting and Best Practices

The Requirements

In order to receive webhooks for a particular order, you will need to have a self-hosted application which will receive and handle postbacks from our system. All postback requests will be made to the URL entered in the notificationUrl field in the body of the POST call made to create an AccountChek order. When passing this URL, ensure that you include https://; if omitted, you will receive an error and will be unable to make the POST call.

Below is an example of an AccountChekAPI request and response containing the notificationUrl.

Request

POST to /v1/accountchekorders

Specification Details

{
    "email": "fake@domain.com",
    "last4SSN": "6789",
    "referenceNumber": "1122334455",
    "firstName": "John",
    "lastName": "Doe",
    "notificationUrl": "https://example.com/accountchek/webhooks",
    "returnUrl": null,
    "phoneNumber": null,
    "employerName": "Informative Research",
    "ssn": "123-45-6789",
    "dateOfBirth": "1983-05-24",
    "address": {
        "street": "1234 Hawthorne Avenue",
        "street2": null,
        "city": "Athens",
        "state": "GA",
        "zip": "31032"
    }
}

See the table below for a list of the fields, a description of each field, and whether they are required or not. Note: Some fields are optional based on the type of verification you are going to be requesting on an AccountChek Order. Make sure to read each description to determine if you need to provide the field for the order.

Response

If the above request is successful, you will receive a HTTP Status 201 - Created. Below is an example of the body of the response.

{
    "id": "b943cae2-a8f5-e911-b5e9-0003ff4f1b49",
    "created": "2019-10-23T15:22:12.967Z",
    "isArchived": false,
    "status": "building",
    "loginUrl": "https://s-borrower.accountchek.net/Account/Login?vodkey=b943cae2a8f5e911b5e90003ff4f1b49",
    "daysRemaining": 58.222795108188656,
    "employmentVerificationRequested": false,
    "email": "johndoe@gmail.com",
    "last4SSN": "6789",
    "referenceNumber": "1122334455",
    "firstName": "John",
    "lastName": "Doe",
    "notificationUrl": null,
    "returnUrl": null,
    "phoneNumber": null,
    "employerName": "Informative Research",
    "ssn": "***-**-6789",
    "dateOfBirth": "1983-05-24T00:00:00Z",
    "address": {
        "street": "1234 Hawthorne Avenue",
        "street2": null,
        "city": "Athens",
        "state": "GA",
        "zip": "31032"
    }
}

If the above request is unsuccessful, you will receive a HTTP Status 422 - Unprocessable Entity. The response body will contain the details of the cause of the error. Below is the structure of an error response.

{
    "general": [
        "string"
    ],
    "properties": [
        {
            "property": "string",
            "message": "string"
        }
    ]
}

What You Will Receive Back

Once the AccountChek order is opened, our system will callback to the notificationUrl provided on the given order when a service status update occurs. The response body will depend on the service (see the different sections below).

Additionally, Webhook postbacks will contain the following header information:

• Content-Length: Length of characters returned in postback.

• Content-Type: application/x-www-form-urlencoded

• User-Agent: AccountChek Webhook

To handle these postbacks, you will need to configure your self-hosted application appropriately.

VOA

The POST request for a VOA webhook contains the following parameters:

• orderId (GUID): This is the ID of the AccountChek order, produced with the initial POST call made to create the given order.

• VOD_ID (GUID): Deprecated/No Function in REST

• orderStatus (int-C#): This is the status of the VOA request for a given orderId.

• reportId (GUID): If the webhook is informing you about a successful report generation (507 status), you will also receive back a reportId. If report generation hasn’t occurred, you won’t receive this back.

VOIE

The POST request for a VOIE webhook contains the following parameters:

Note: the VOIE service webhooks require opting in to receive them. To opt in, please reach out to AccountChek support.

• orderId (GUID): This is the ID of the AccountChek order, produced with the initial POST call made to create the given order.

• orderStatus (int-C#): This is the status of the VOIE request for a given orderId. These are the statuses that may be received:

• voeReportId (GUID): If the webhook is informing you about a successful report generation (607 status), you will also receive back a voeReportId. If report generation hasn’t occurred, you won’t receive this back.

Troubleshooting and Best Practices

In order to successfully receive notifications, the URL provided above must be exposed and able to handle postbacks. To ensure this is the case, account for the following:

Webhook Postman Collection

In order to troubleshoot any issues you may be experiencing with the webhooks, we provide an example Postman Collection which is structured exactly how the AccountChek System will send the webhooks.

Webhook Postman Collection

Your provided URL doesn’t require authentication

Our system does not accommodate extra authentication methods. For example, a notificationUrl requiring a custom token to be passed in the header of the callback request will not work.

Your network is optimized to handle external requests

For example, if your network is configured to block external requests with a User-Agent longer than a certain character length, you won’t receive postbacks.

You have correctly mapped the returned values in the webhook

When the POST is made to the URL provided for a given order, the values detailed above are returned and your webhook controller must match the names of each returned field. If this isn’t done correctly, you will likely experience issues for each incorrectly named property.

You have whitelisted our IPs in your network (if required)

If using a firewall or security measure that requires whitelisting to receive our postbacks, please reach out to ac-integration@informativeresearch.com for the current list of AccountChek IPs.

You have opted in to VOIE webhooks (if wanting to use them)

VOIE service webhooks require opting in to receive them while VOA are available by default. To opt in to VOIE webhooks, please reach out to AccountChek support.