Report Webhook Events

Overview

Webhooks are sent throughout the generation process for reports within Credit Decisioning. Webhooks will typically alert you when a report has started the process, when a report has had updates, when a report has failed to generate, or when a report has finished the generation process. Webhooks are generated when the callBackUrl is specified on the Generate call for the report. All callBackUrls must be HTTPS.

Example VOA Report Webhook

POST
/decisioning/v1/customers/{customerId}/voa?callbackUrl=https%3A%2F%2Fwww.mydomain.com%2FfinicityReports%2Flistener

The content type of the body of the webhook will match Accept type of the Generate report call (application/json, application/xml).

Webhooks will only be sent once. There is no retry policy. Webhooks require that the endpoint being called not have any security restrictions.

In addition, webhooks should be processed immediately. Any processing of webhook data must happen on another thread.

Event Body

The general format of the webhook body will contain the following fields:

FieldDescription
eventNameThe event name of the webhook. This will either be inProgress, failed, primaryFieldUpdate, or done.
idFinicity’s report ID
consumerIdFinicity’s consumer ID. This field is optional and may not always return.
consumerSsnThe last four of the consumer’s social security number. This field is optional and may not always return.
typeFinicity’s report type. This field is optional and may not always return.
statusinProgress, success, failure, or editing
customerIdFinicity’s customer ID. This field is optional and may not always return.
portfolioIdFinicity’s portfolio ID. This field is optional and may not always return.

Event Types

Every report webhook event type that the partner will receive is listed below.

Some events aren’t applicable for certain types of Finicity Connect.  The following table will direct you to which ones are applicable for the flow you are utilizing.

Event TypevoavoaHistoryvoipreQualVoavoieTxVerifypayStatement
inProgressXXXXXX
failedXXXXXX
primaryFieldUpdateXX
doneXXXX

In Progress

The inProgress webhooks are sent when a report has been generated.

Sample In Progress Event
 {
"id":"reportId",
"eventName": "inProgress",
"consumerId": "conId",
"consumerSsn": "conSSN",
"type": "reportType",
"status": "inProgress",
"customerId": 123,
"portfolioId": "asdf-1-port"
}

Failed

The failed webhooks are sent when a report has failed generation.

Sample Failed Event
 {
"id":"reportId",
"eventName": "failed",
"consumerId": "conId",
"consumerSsn": "conSSN",
"type": "reportType",
"status": "failure",
"customerId": 123,
"portfolioId": "asdf-1-port"
}

Primary Field Update

The primaryFieldUpdate webhooks are sent when a VOIE report has gone through primary field extraction.

Sample Primary Field Update Event
 {
"id":"reportId",
"eventName": "primaryFieldUpdate",
"consumerId": "conId",
"consumerSsn": "conSSN",
"type": "reportType",
"status": "success",
"customerId": 123,
"portfolioId": "asdf-1-port"
}

Done

The done webhooks are sent when a report has successfully generated.

Sample Done Event
 {
"id":"reportId",
"eventName": "done",
"consumerId": "conId",
"consumerSsn": "conSSN",
"type": "reportType",
"status": "success",
"customerId": 123,
"portfolioId": "asdf-1-port"
}