How to Use Webhooks to Respond to Bank Statements API Events

A webhook is an HTTP endpoint with access to your backend that receives events from the Talefin’s Bank Statements API.

Webhooks allow you to be notified about events such as:

Updates on a crawler job status (crawler.lifecycle_update)
The completion of an analysis of a bank account (analysis.report_ready)

You will need access to the Talefin Bank Statements Dashboard to set up a webhook. Talefin will provide a Dashboard username and password after provisioning your account. For testing purposes and to see the flow of the events being sent to your system, we recommend using a webhook from webhook.site. To do that, copy the link from webhook.site and add it to your webhook via the Bank Statements Dashboard. In production, you will have to provide the link to your webhook to us.

Bank Statements API Events Table

The table below describes the events sent by the Bank Statements API in the order they are sent.

Event	Description
`crawler.lifecycle_updated (status QUEUED)`	This event is sent during the selection of the bank institution by the client.
`crawler.lifecycle_updated (status PROCESSING)`	This is event is sent while loading the selected bank institution crawler.
`crawler.lifecycle_updated (status AUTH)`	This is event is sent when the authentication credentials collection fields are presented to the client. This stage is bypassed during application refreshes.
`crawler.lifecycle_updated (status TIMEDOUT)`	This event is sent when the client does not supply their authentication credentials within a 10-minute period of the authentication credentials collection fields being presented to the client.
`crawler.lifecycle_updated (status FAILED)`	This event is sent when the crawler raises an expected error.
`crawler.lifecycle_updated (status RELEASED)`	This event is sent after the client has provided their authentication credentials and the crawler is accessing their online bank portal to download their transaction data, balance information, etc.
`crawler.lifecycle_updated (status DIED)`	This event is sent when the crawler raises an unexpected error.
`crawler.seed_created`	This event is sent after the client authentication credentials and account selection (consent) have been encrypted and stored. This event is bypassed with application refreshes. The seed should be recorded somewhere secure in your system as it will be required to initiate a refresh.
`account.numbers_ready`	This event is sent during additional collection of account BSB and number. It is sent just after the `crawler.lifecycle_updated (status RELEASED)`. and releases the BSB and account numbers for all accounts being processed. Example: [{"bsb": "123456", "number": "1234567"}, {"bsb": "123456", "number": "1234567"}]. It requires the balance collection service parameter.
`account.balances_ready`	This event is sent during additional collection of current and available account balances. It requires the balances collection service parameter. It is sent after `account.numbers_ready` and 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.owner_info`	This event is sent when account owner information is retrieved by the crawler for each account analysis. The account owner information allows for verification of the owner's name, address and mobile that is registered for each bank account. This event requires the account owner collection service parameter.
`crawler.lifecycle_updated (status COMPLETE)`	This event is sent after all the logic checks on transaction data, additional collection and crawler seed created.
`client.submission_complete`	This event is sent after the client has finalised their multiple institution submission through the pressing of the application complete button in the Iframe. It requires the `multiple=true` collection service parameter.
`analysis.report_ready`	This event is sent after the generation of the account analysis once the crawler has retrieved the account transaction data. You can use this event to know when to collect the report JSON, and eStatement/s for a specific account.
`analysis.html_ready`	This event is sent after the analysis HTML for a specific account is ready to be collected. It requires the vendor setting print html checked.
`analysis.pdf_ready`	This event is sent after the analysis PDF for a specific account is ready to be collected. It requires the vendor setting print pdf checked.
`summary.report_ready`	This event is sent after the generation of the application summary, which is a JSON file containing all the metrics for a particular application.
`summary.html_ready`	This event is sent after the generation of the summary HTML and it requires the vendor setting print html checked.
`summary.pdf_ready`	This event is sent after the generation of the summary PDF and it requires the vendor setting print pdf checked.
`summary.pdf_ready`	This event is sent after the generation of the summary PDF and it requires the vendor setting print pdf checked.
`application.combined_pdf_ready`	This event is sent after the generation of the combined analysis pdf document, which is a combination of analyses and summary PDFS into a single PDF file. It requires the vendor setting uses combined analysis pdf checked.
`application.report_ready`	This event is sent after the generation of the application report, `report.json`, which include application metrics, profiles, account ids, and analysis ids. Note: this happens before PDFS and HTMLS are cached.
`application.bundle_ready`	This event is sent after the generation of the application document bundle, `bundle.json`, which includes all the documents, account analysis and application summary on a single JSON file for archiving purposes. You would usually fowllow this event by a single request to `/api/application/{application_id}/bundle` which would deliver. 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">
5</form>

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

Event Payload Examples

1{
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  }
22}
23
24{
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  }
45}
46
47{
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  }
68}
69
70{
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  }
77}

Example Account Owner Payloads

Success

1{
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    }
26}

Failed

1{
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    }
14}

Authentication

Authenticating with TaleFin’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.

IP Whitelisting

Webhooks from TaleFin originate from the following IP addresses. These are provided so you can allow access by these addresses through a firewall you are using.

Production IP address: 34.87.247.183

Staging IP address: 34.151.65.130