Webhooks Guide

Managing Application Events via Webhook Callbacks

Application Events Table

As with the API integration, callbacks will be returned to your backend system via a webhook which can be configured as per the API Documentation. You can create multiple webhooks which will be called, in series, when events occur during the application life cycle.

A username and password for this will be provided when your account is provisioned by Credfin.

A webhook would usually be an API endpoint with access to your backend. It could be a GCP Cloud Function or an AWS Lambda. It could also be part of your larger backend system hosted on a dedicated server or cloud set up.

crawler.seed_createdThis is called once the crawlers have successfully logged in. The iFrame will produce an event “RELEASED” which means no further inputs from the customer are necessary. The seed should be recorded somewhere secure in your system as it will be required to initiate a refresh.
crawler.lifecycle_updatedThis event fires as the crawler progresses along its lifecycle. Useful to notify your backend of the progress of the front end.
account.numbers_readyFires just after the released lifecycle in crawler.lifecycle_updated. Releases the bsb and account numbers for all accounts being processed.
Example: [{"bsb": "123456", "number": "1234567"}, {"bsb": "123456", "number": "1234567"}]
account.balances_readyFires after application.account.numbers_ready. Releases the account balances for use.
Example: [{"bsb": "123456", "number": "1234567", "available": "3.98", "balance": "3.98"}, {"bsb": "123456", "number": "1234567", "available": "3.98", "balance": "3.98"}]
account.account_ownerThis is fired once the account owner's details have been collected and are available. These details are sent as part of the payload as seen in the examples section below.
analysis.report_readyThis event will fire each time an account has finished being analyzed. You can use it to know when to collect the report JSON, and eStatement/s for a specific account.
application.report_readyWill be called as soon as the analysis bundle for the entire application as well as metrics is ready, but before the PDFs and HTMLs are cached.
analysis.pdf_readyWill be called when the analysis PDF for a specific account is ready to be collected.
analysis.html_readyWill be called when the analysis HTML for a specific account is ready to be collected.
summary.pdf_readyPDF containing all the metrics is ready.
summary.html_readyHTML containing all the metrics is ready.
application.bundle_readyCalled once all accounts have been analyzed and PDFs & HTML are ready. This event would usually be followed by a single request to /api/application/{application_id}/bundle which would deliver all JSON, PDFs, HTML, and eStatements in a single request. Note: PDFs & HTML reports can be excluded from this bundle via configuration options in the dashboard but you will still need to wait for them to be cached. If your implementation is time-sensitive, use the application.report_ready to drive your decision engine then collect the PDFs individually or collectively by pulling the bundle when you get application.bundle_ready.

In the dashboard there are two configuration options to turn on and off the analysis and eStatement PDFs & HTML is included in the report JSON and bundle JSON files.

Sometimes the end-user will select the incorrect bank or change their mind. If a crawler is simply abandoned you will receive a TimeOut error from the crawler. This can cause a false error; to handle this case there is an Exit signal that can be sent to the crawler instance which will initiate a graceful shutdown.

Example HTML to initiate this endpoint

1<form action="io" method="POST">
2    <input type="hidden" name="csrfmiddlewaretoken" value="[some_token]">
3    <input type="hidden" name="exit" value="exit">
4    <input type="submit" value="Exit" class="button-primary mt-3 px-3">

All you need to provide is an element called “exit” with the value of “exit” and the crawler will be shut down.

Example Payloads

2  "event": "application.bundle_ready",
3  "payload": {
4      "id": 961194,
5      "vendor_specific_id": "200120c",
6      "timestamp": "2020-01-21T12:52:23.480539+11:00",
7      "crawler": [
8      {
9          "uuid": "8bb8ba28-9f5f-408b-844c-16cc400b1cfd",
10          "application": 961194,
11          "bank_id": 130,
12          "timestamp": "2020-01-21T12:52:23.486783+11:00",
13          "status": "COMPLETED"
14      }
15      ],
16      "full_name": "Mickey-Mouse",
17      "email": "mickey@mice.com",
18      "mobile": "0412345678",
19      "finalised": true,
20      "analysed": true
21  }
25  "event": "summary.report_ready",
26  "payload": {
27      "id": 961194,
28      "vendor_specific_id": "200120c",
29      "timestamp": "2020-01-21T12:52:23.480539+11:00",
30      "crawler": [
31      {
32          "uuid": "8bb8ba28-9f5f-408b-844c-16cc400b1cfd",
33          "application": 961194,
34          "bank_id": 130,
35          "timestamp": "2020-01-21T12:52:23.486783+11:00",
36          "status": "COMPLETED"
37      }
38      ],
39      "full_name": "Mickey-Mouse",
40      "email": "mickey@mice.com",
41      "mobile": "0412345678",
42      "finalised": true,
43      "analysed": true
44  }
48  "event": "application.report_ready",
49  "payload": {
50      "id": 961194,
51      "vendor_specific_id": "200120c",
52      "timestamp": "2020-01-21T12:52:23.480539+11:00",
53      "crawler": [
54      {
55          "uuid": "8bb8ba28-9f5f-408b-844c-16cc400b1cfd",
56          "application": 961194,
57          "bank_id": 130,
58          "timestamp": "2020-01-21T12:52:23.486783+11:00",
59          "status": "COMPLETED"
60      }
61      ],
62      "full_name": "Mickey-Mouse",
63      "email": "mickey@mice.com",
64      "mobile": "0412345678",
65      "finalised": true,
66      "analysed": true
67  }
71  "event": "analysis.report_ready",
72  "payload": {
73      "id": 22749,
74      "time": "2020-01-21T12:52:47.779186+11:00",
75      "vendor_specific_id": "200120c"
76  }

Example Account Owner Payloads


2    "status": "success",
3    "fileLocation": "account_owner_info-325185-03531384.json",
4    "messageType": "account_owner_info",
5    "errorMessage": "",
6    "accountOwnerInfo": {
7        "bsb": "325185",
8        "number": "03531384",
9        "address": [
10        {
11            "addressLine1": "29 SOUTH TERRACE",
12            "addressLine2": "QUORN SA 5433",
13            "streetNumber": "29",
14            "streetName": "SOUTH",
15            "streetType": "TERRACE",
16            "townSuburb": "QUORN",
17            "state": "SA",
18            "postCode": "5433",
19            "country": "AU"
20        }
21        ],
22        "owners": ["MISS T J COULTHARD"],
23        "email": [],
24        "phone": []
25    }


2    "status": "failed",
3    "fileLocation": "account_owner_info-062692-44520485.json",
4    "messageType": "account_owner_info",
5    "errorMessage": "No eStatements available",
6    "accountOwnerInfo": {
7        "number": "44520485",
8        "bsb": "062692",
9        "address": [],
10        "owners": [],
11        "email": [],
12        "phone": []
13    }

Authenticating with Credfin’s API backend is done via HMAC. You will need this if you wish to collect any reports and analyses from the backend. The tokens can be created by visiting the API documentation, or through our dashboard.

Subscribe to our newsletters

Subscribe to our newsletter and stay up to date with the latest news about Credfin.