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
![](../screens/Webhook_Architecture.jpg)
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
![](../screens/Webhook_Workflow.jpg)
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.
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
|