Appendix E :Webhooks

E.1 Introduction

The Webhook option in OFSLL extends the support of interfacing with third-party applications by sending REST API based notifications of changes through system generated Webhook event actions.

In the Webhook integrated model, it is the server to client direction of conversation in which the server pushes data to the client that hosts an HTTP based API endpoint. OFSLL uses the existing weblogic key-store to register third-party application credentials such as User Name, Password and SSL/TSL Certificate.

E.2 Webhook Architecture

As per the above image:

• A change in the base system can either be triggered by an user performed action or through REST API call.
• The ‘Events’ refer to system generated information indicating the change in system which is to be propagated to third-party applications that are interfaced with OFSLL. For more information on configuring events in the system, refer to Events section.
• The ‘Webhook UI’ is the Webhook setup screen in which Webhook definitions (channel) and Event Details are defined by registering third-party applications that are interested in OFSLL events. For more information on configuring Webhook in the system, refer to Webhook section.
• The ‘Webhook Adapter’ is Webhook MDB (Message Driven Bean) and is used to propagate OFSLL messages to thrid-party applications.

E.3 Webhook Workflow

As per the above workflow:

• On defining WEBHOOK, a WEBHOOK action is added to Events framework.
• Based on the Event definition defined in setup, system triggers Events.
• For all Events with WEBHOOK as the associated action, AQ JMS message is generated and the same is consumed by WEBHOOK MDB adapter. If there is one Event subscribed to 5 channels then system places 5 WEBHOOK messages into MDB.
• WEBHOOK MDB read the channel configuration detail from both Database and WebLogic CSF to propagate JSON message.
• Based on the outcome of call to the third-party application, system updates the STATUS and HTTP response code for the message.
• A retry batch job picks the failed messages and then resubmit into AQ. The number of retries is based on System Parameter which cannot exceed more than 5.

E.4 Webhook Message Format

Webhook Events are published in json message format. This message content can be customized using Response User Defined Tables. For more information on json message format, refer to Events section.

To send/receive data between OFSLL and external systems Request/Response entities are used. OFSLL allows to send Header/Body details for data transfer with each Request/Response.

As indicated below,

• Header consists of key value pairs some are standardized and other can be specific to implementation.
• Body details are defined either in XML/JSON.

  

E.5 Processing Webhook Request

• When an event is triggered in OFSLL, system checks if there are any Webhook actions defined for different channels.
• If there are multiple registries available, OFSLL creates multiple WEBHOOK messages to propagate event details to the third-party applications.
• WEBHOOK MDB reads the messages and generates response based on User Defined Table available for individual Events.
• When response data is generated, system generates POST request to third-party applications and marks these requests as COMPLETED on successful notification.
• If the third-party notification is failed, OFSLL updates the message as FAILED.
• On receiving the notifications, OFSLL expects third-party application’s POST service to return one of the following HTTP status code:

  HTTP Status Code	MDB Dashboard Status	Description
  2XX, 3XX	COMPLETED
  4XX	FAILED	Need to resubmit manually. MDB will update retry count to 5
  5XX	FAILED	Will be resubmitted by batch job

• The system parameter EVI_MAX_RETRY_COUNT records and controls the maximum attempts to re-trigger the FAILED status messages which cannot exceed more than 5 times. However, this parameter can be modified if the maximum re-trigger attempts is to be less than 5 times.
• The batch job EVEPRC_BJ_100_02 in SET-EVE batch job set picks the FAILED status messages for re-trigger and considers the above system parameter to control the maximum attempts to re-trigger.
• The system parameter CMN_HTTP_CONNECTION_TIMEOUT determines the maximum allowed response time (in seconds) from the third-party application. If response time exceeds than the system parameter configured value, then the status of request is updated as FAILED with 500 HTTP Status Code.
• If the system is running behind a firewall/proxy network, OFSLL provides below system parameters to configure proxy details.

  System Parameter	Description
  CMN_HTTP_PROXY_ENABLED_IND	PROXY INDICATOR FOR ALL OUTSIDE HTTP/HTTPS CONNECTION
  CMN_HTTP_PROXY_PORT	HTTP PROXY SERVER PORT FOR OUTGOING HTTP CONNECTIONS
  CMN_HTTP_PROXY_SERVER	HTTP PROXY SERVER FOR OUTGOING HTTP CONNECTIONS

E.6 Webhook Support for OBRH Integration

OFSLL supports integration with OBRH (Oracle Banking Routing Hub) which is used to Authenticate, Invoke and Route request from Source to Destination using SOAP/Rest Api.

Below is a representation of OBRH process indicating how data from source (Service Consumer) is processed to destination (Service Provider) using OBRH gateway which supports transforming, routing, authenticating the request and response.

For details about the request and response format, refer to ‘Webhook Message Format’ section.

E.6.1 OBRH Interfacing support

Webhook in OFSLL facilitates to send Event outcome data to external system. If the external system is OBRH which is the endpoint to receive and process Event data payload from OFSLL, ensure that the Authentication Mode in Webhook is configured to ORACLE BANKING ROUTING HUB. For more information, refer to ‘Webhook Definition’ section.

Below is an illustration indicating the flow of data between OFSLL and OBRH.

• OFSLL Webhook generates events which are configured for specific actions.
• From Webhook, the data is transferred in the form of Request using http protocol and is first authenticated in an Authenticate Server. On authentication, a response is received in Response Token Key.
• Post authentication, to connect OBRH, OFSLL further needs to send addition Authentication attributes and Request Header. The same can be defined in Attribute Value field of Webhook definition. For more information, refer to ‘Authentication Attributes’ section.

Below are some of the example of Attribute Values that can be defined for OBRH headers:

Attribute Value	Example
TOKEN REQUEST HEADER	appId
REQUEST HEADER	entityId appId branchCode userId SERVICE-CONSUMER SERVICE-CONSUMER-SERVICE

Note

OBRH currently does not support return of customizing HTTP header [X-Hmac] because of which enable of Verified indicator using Test button cannot be done. Verification func­tionality should be done manually/via script and needs to be automated using OBRH once new feature of customizing HTTP header is enabled.