Appendix C :Webhooks

C.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.

C.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.

C.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.

C.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.

C.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