Real-time / Webhooks

Data Direct: Real-time provides a webhook mechanism for event delivery. A webhook is a web application which receives banking event data.

Events delivered via webhook are sent in a JSON format from Apiture Digital Banking (ADB) directly to a Financial Institution (FI) or third-party’s application. The FI or third-party provides Apiture with a URL where their application that processes the event data lives, and Apiture delivers the event data to that location as events occurs. When an event occurs, the event delivery is attempted in near real-time.

Creating and Managing Webhooks

Webhooks are created and maintained by the Financial Institution or other third-party. Information about the webhook is provided to Apiture via the Developer Portal.

For help with the initial onboarding process, see our onboarding article. This article should be used for reference at the same time as the onboarding article.

To learn more about registering for Data Direct: Real-Time event delivery in the Developer Portal, see our article within the documentation of the Authenticated portion of the Developer Portal.

This article provides guidance for creating a webhook that can process Data Direct: Real-Time events, including the structure of the webhook and reading the provided data. Registration of the webhook on the Developer Portal is required in order to receive event data delivery.

Receiving and Processing Data

An application to receive the webhook data must be available via an HTTPS URL. The JSON data sent follows the structure discussed in the Webhook Structure section.

The application must require either a username and password combination or 0Auth 2.0 Client Credentials for Authentication. The Authentication information is provided to Apiture when the webhook is created. More information on this is discussed in the Authentication section.

Apiture pushes new Events to the HTTPS URL and uses the Authentication method to verify it is a secure source of data.

After data is received, the application may process and use the data however it is needed.

Secured Connection Required

Event Webhooks only work over an HTTPS connection. An HTTP connection is not allowed as it is considered a security risk.

Event Structure

The format description is available at General Structure. The event structure is the same as other event data.

Delivery Failure

If a webhook fails to deliver or receive an event, it will attempt to deliver the event again after a short delay. If it fails to deliver the event repeatedly, the webhook will be temporarily suspended until an automatic test determined the webhook connection is working properly again. Event data accumulated during this time are not lost, but are not delivered in near real-time.

Webhook Structure

Apiture requires the following information to create a webhook connection.

Every webhook has a:

URL
list of categories
authorization type
state
[Optional] description

URL

The URL is the location where Events are sent. This location is determined by the FI. This URL is not hosted by Apiture and is usually connected to the FI’s backend for data processing.

Categories

There are many categories of events, which can be used to include or exclude certain event data. For example, if an FI desires a webhook to only monitor wire transfers events, they would only include the wireTransfers category.

There is no limit to the amount of categories that a webhook can have.

To browse the available events and their categories, view our Event Documentation.

Webhook Authorization

Each webhook has an authorizationType property which indicates which type of authentication. The type of Authorization are:

basic
oauthClientCredentials

The details of setting up each Authorization type are detailed in the Authorization section within this article.

Webhook State

Each webhook has a state property which indicates whether events should be routed to it. Some states are set automatically, while others can be requested if needed. The states are:

Enabled: Events are sent to this webhook.

Deactivated: The webhook has been manually suspended. The webhook can be reactivated at any time by using the developer portal.

Suspended: Apiture has automatically stopped events from being sent to this webhook, because it has had multiple, consecutive failures, such as responding with a 4xx or 5xx error code. Apiture may contact the webhook owner when a webhook is in a suspended state, if it seems necessary to resolve the issue.

The webhook will be unsuspended by Apiture once a successful test is completed. The test checks for a successful response (such as a 200 OK response) before automatically reenabling the webhook.

Disabled: Events will not be sent to this webhook due to a detected issue. The webhook will not be re-enabled.

Deleted: A deactivated webhook can be deleted, fully removing the webhook.

Description

This optional field is a human-readable description of the webhook.

Authorization

The authorization type is selected when the webhook is set up. There are two types:

Basic

When the authorization method is basic, then a Webhook is expected to use a username and password for authorization.

OAuth / Client Credentials

When the authorization method is Client Credentials using OAuth, then a Webhook is expected to have the following properties provided by the FI:

A clientId, submitted as a one-line string. Do not include line breaks.
A clientSecret, submitted as a one-line string. Do not include line breaks.
A tokenUrl is hosted by the FI and is not hosted by Apiture. It must have an HTTPS URL.
The scope is the space-delimited scope values Apiture needs to Authenticate with the FI or third-party’s application. These scopes are defined by the FI or third-party, and are not the scopes associated with Apiture APIs.

The OAuth Client Credentials follows the same required format and process as authenticating for any Apiture API. Documentation on how to perform OAuth Authentication is available here. The most relevant information starts at the “POST to the token_endpoint” section.

Note: The token_endpoint referenced in the linked article is the conceptually the same as the tokenURL that is provided to Apiture within this article, with the FI or third-party’s application the taking place of an API.

The FI or third-party’s application must validate the required Authorization header and reject invalid or expired access_token values to ensure secure communication.