Skip to main content

Async callbacks

Overview​

Informed will POST the relevant asynchronous callback responses to the webhook that you specify.  If your webhook does not respond with a 2xx (success), Informed will re-submit the request to your endpoint up to 5 times using a delay strategy.

info

Informed will retry as mentioned above if your endpoint returns a 429, 500, 502, 503 or 504 status.

The key attributes of your callback endpoint are shown below:

  • Your endpoint must support the HTTPS protocol, with a valid certificate.
  • Your endpoint should return a 200 response status upon receiving the callback payload.
  • If your endpoint returns any body in the success response, it must be json-formatted.
  • If you have authentication configured on your endpoint (recommended), you must provide that information to Informed.
  • If you need to whitelist any IP addresses on your side for the callback, you can find those here.

Process Flow​

Please reference the full sequence diagram.

Callback types​

All callbacks will have an event_type node that specifies what type of callback it is. The relevant event types associated with the income calculation service are as follows:

  • extractions
  • income_calculations
  • error

The sections below provide more detail on the contents of the various callbacks.

Extraction Callbacks​

The extraction service provides the extracted data from the document types found in a submitted image file. Bear in mind that Informed can separate out multiple documents from a single PDF or TIFF file. At the present time, you will receive one extraction callback per original file submitted (provided you specify the extract service when registering the application).

tip

While you will only receive one extraction callback per original file submitted, if that single file contains multiple documents of different types, you can expect to receive a response containing multiple classified documents and the associated extracted data.

In the example callback payload below, there are a couple things to note:

  • The application_id will be the same one provided in the synchronous response to the original application registration.
  • The application_reference_id will be the same reference id that you provided when you registered the application.
  • The documents object will contain keys for each document classification type encountered in the file.
  • Each of those document types will contain a list of the documents of that type found in the file.
  • Every individual derived document identified will receive a unique document_id.
  • Every individual derived document will also contain a reference to the original file_ids (from the synchronous response) and file_reference_ids (the file name you assigned at the time of upload).
  • The url provided for each derived document is a time-bound, pre-signed S3 URL, which you can use via a GET call to retrieve the indexed document image.
  • Details about what items are extracted for a given document type can be found on the components page.
danger

There is no guarantee that the file download URL's (typically AWS S3 pre-signed URL's) will remain exactly the same for all future time. Informed reserves the right to use whatever infrastructure is most secure and efficient.

If you are trying to whitelist the download URL's, at the current time, as Amazon AWS pre-signed URL's, they will have a base domain of amazonaws.com, so the most restrictive that you should make your whitelist is *.amazonaws.com.

Extraction Callback Example
{
  "event_type": "extractions",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "your_unique_application_id",
  "documents": {
    "paystub": [
      {
        "data_action": "create",
        "document_id": "c9d0571f-fe7c-4f82-83bc-117b91bfaaf8",
        "file_ids": [
          "cb47b001-84e1-43c2-a94e-686bd46e5bee"
        ],
        "file_reference_ids": [
          "paystub.pdf"
        ],
        "url": "https://informed-techno-core-<env>-downloads.s3.amazonaws.com/123...",
        "extracted_data": {
          "applicants": {
            "applicant1": {
              "address": {
                "street_address": "8717 S 4th Ave",
                "street_2": null,
                "city": "Inglewood",
                "state": "CA",
                "zip": "90305"
              },
              "first_name": "Jo",
              "middle_name": null,
              "last_name": "Boren",
              "suffix": null,
              "ssn": "3906"
            }
          },
          "employer_name": "Informed, Inc.",
          "pay_begin_date": "2021-03-01",
          "pay_end_date": "2021-03-15",
          "pay_date": "2021-03-16",
          "regular_pay": {
            "current": 2880.0,
            "ytd": 11100.0
          },
          "gross_pay": {
            "current": 5392.0,
            "ytd": 15976.0
          },
          "overtime_pay": {
            "current": 1512.0,
            "ytd": 3456.0
          },
          "garnishments": {
            "current": 0.0,
            "ytd": 0.0
          },
          "loans401_k": {
            "current": 0.0,
            "ytd": 0.0
          },
          "bonus_pay": {
            "current": 1000.0,
            "ytd": 1000.0
          },
          "commission_pay": {
            "current": 0.0,
            "ytd": 0.0
          },
          "tips_pay": {
            "current": 0.0,
            "ytd": 0.0
          },
          "pay_period_frequency": "Semimonthly",
          "hours_worked": 80.0,
          "sick_pay": {
            "current": 0.0,
            "ytd": 0.0
          },
          "vacation_pay": {
            "current": 0.0,
            "ytd": ""
          },
          "net_pay": {
            "current": "",
            "ytd": ""
          },
          "earnings": [
            {
              "type": "gross_pay",
              "description": "Total pay",
              "current": 5392.00,
              "ytd": 15976.00
            },
            {
              "type": "regular_pay",
              "description": "Total base pay earnings",
              "current": 2880.00,
              "ytd": 11100.00
            }
          ],
          "deductions": [
            {
              "type": "medical",
              "description": "Medical insurance deductions (e.g. Medical Insurance, Critical Illness Insurance, Cancer Insurance)",
              "current": 1740.24,
              "ytd": 217.53
            }
          ],
          "taxes": [
            {
              "type": "federal_withholdings",
              "description": "Federal tax withholdings",
              "current": 438.99,
              "ytd": 2867.89
            }
          ]
        },
        "updated_at": "2023-07-31T03:34:20Z"
      }
    ]
  }
}

Full Extractions Schema​

View extended example of extractions schema for all major consumer document types.

Income Calculation Callbacks​

The income calculation service analyzes the submitted documents and calculates an income based on the extracted data from the document types found in the aggregate of the submitted image files. The calculated income is returned in an asynchronous income_calculations event payload.

Unlike the extractions service, for which we can predict one callback per original submitted file, it is not as straight forward for the income calculation callbacks. The number of income calculation callbacks will depend on several factors, such as the time gap between uploading the original files and the size and complexity of the uploaded files. The important thing to remember is that the income calculation callbacks will always represent the aggregate analysis across all associated documents available at the time the income calculations are run.

tip

In order to help eliminate any confusion in the case of multiple income calculation callbacks, we have added the data_sources element, which specifies the uploaded files that were available/present at the time of generating the calculated income. This element will also allow you to track that all previously uploaded documents for an application have been analyzed.

In the example callback payload below, there are a couple things to note:

  • The application_id will be the same one provided in the synchronous response to the original application registration.
  • The application_reference_id will be the same reference id that you provided when you registered the application.
  • If any paystubs were found to be a potential match to paystub templates known to be fraudulent, we will designate those paystub document_ids in the suspected_fraudulent section.
Income calculation Callback Example
{
  "event_type": "income_calculations",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "your_unique_application_id",
  "income_calculations": {
    "applicant1": {
      "incomes": [
        {
          "year": 2021,
          "income_sources": [
            {
              "source_type": "employed",
              "calculated_income_amount": 69120.0,
              "document_ids": [
                "c9d0571f-fe7c-4f82-83bc-117b91bfaaf8"
              ]
            }
          ]
        }
      ],
      "suspected_fraudulent": {
        "document_ids": [

        ]
      }
    }
  },
  "data_sources": {
    "image_files": [
      {
        "file_id": "cb47b001-84e1-43c2-a94e-686bd46e5bee",
        "file_reference_id": "paystub.pdf"
      }
    ],
    "structured_data": [

    ]
  }
}

Error Callbacks​

If something goes wrong during the processing of the application such that a normal asynchronous callback cannot be returned, Informed will return an asynchronous error callback.

Physical image defects​

If you were to upload a corrupted file, password-protected file or non-image file (e.g., .txt file), then you should expect to receive an asynchronous callback response similar to the examples below, instead of the normal extractions response.

Generic issues​

{
  "event_type": "error",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "error_message": "unable to process this file",
  "file_id": "unique-Informed-file-id",
  "file_reference_id": "partner file name or id",
  "webhook_url": "https://your.callback.com/here"
}
{
  "event_type": "error",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "error_message": "The file type is invalid. The valid file types are .pdf, .tiff, .jpeg, .jpg, .png.",
  "file_id": "unique-Informed-file-id",
  "file_reference_id": "partner file name or id",
  "webhook_url": "https://your.callback.com/here"
}

Corrupted file​

{
  "event_type": "error",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "error_message": "identify: no decode delegate for this image format `' @ error/constitute",
  "file_id": "unique-Informed-file-id",
  "file_reference_id": "partner file name or id",
  "webhook_url": "https://your.callback.com/here"
}

Password-protected file​

{
  "event_type": "error",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "error_message": "**** This file requires a password for access",
  "file_id": "unique-Informed-file-id",
  "file_reference_id": "partner file name or id",
  "webhook_url": "https://your.callback.com/here"
}

Physical image dimensions​

If you were to upload a file with dimensions of less than 100x100 pixels, then you should expect to receive an asynchronous callback response like the one below, instead of the normal extractions response.

{
  "event_type": "error",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "error_message": "The image dimension is invalid.",
  "file_id": "unique-Informed-file-id",
  "file_reference_id": "partner file name or id",
  "webhook_url": "https://your.callback.com/here"
}

Physical image size​

If you were to upload a file over 80 MB in size, then you should expect to receive an asynchronous callback response like the one below, instead of the normal extractions response.

{
  "event_type": "error",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "error_message": "The file size is too large. It should be less than 80MB.",
  "file_id": "unique-Informed-file-id",
  "file_reference_id": "partner file name or id",
  "webhook_url": "https://your.callback.com/here"
}

Income calculation error​

If the income calculation process encounters an error, then you should expect to receive an asynchronous callback response like the one below, instead of the normal income calculation response. Note that the error message says the response is delayed, but in reality the income calculation response will not be coming if you get this message.

{
  "event_type": "error",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "webhook_url": "https://your.callback.com/here",
  "error_message": "Verification response is delayed"
}