Incremental Loan Replication

In this tutorial, we'll provide a brief overview of webhooks and explain how to use them for synchronizing loan data in real-time.

Put simply, a webhook is an HTTP callback that is triggered when a loan file is created, updated or submitted. For more background, please refer to Webhook.

Webhook Subscription

To get started, you must create a webhook subscription using the create subscription API. Remember, the relationship between a webhook subscription and Encompass instance is 1:1. Attempting to create a second subscription will simply update the existing one.

Webhook Callback

With Spring Boot, the best option for implementing the webhook callback is a RestController, as shown in Figure 1.

@RequestMapping(path = "/callback", method = RequestMethod.POST)
@ResponseStatus(HttpStatus.OK)
public void handle(@RequestBody Notification notification) throws IOException {
  String loanId = notification.getMetadata().getResourceId();

  System.out.println(String.format("Processing loan %s", loanId));

  //obtain access token
  Client client = new Client.Builder()
    	.setBaseUrl(baseUrl)
    	.setClientId(clientId)
    	.setClientSecret(clientSecret)
    	.setUsername(username)
    	.setPassword(password)
    	.build();

  //process loan data
  List<String> loanBatch = Arrays.asList(new String[]{loanId});
  String pipeline = client.getPipelineForLoanIdsAsString(loanBatch);

  Files.write(
    	Paths.get(this.outputFile).toAbsolutePath(),
    	pipeline.getBytes(),
    	StandardOpenOption.CREATE,
    	StandardOpenOption.APPEND);
}

When triggered, the callback retrieves the loan GUID from the notification (line 4) and then processes the loan (lines 18-25). Since a notification is purged from the Encompass Platform once it is acknowledged, exception handling is critical. Be sure to process and/or persist the notification before returning a 2xx status code. If the callback fails to acknowledge a notification, the Encompass Platform will attempt redelivery.

Signature Verification

We'll use a HandlerInterceptorAdapter to intercept and preprocess requests. In this case, the pre-processing includes verifying the message signature as shown in Figure 2.

@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)
  	throws Exception {
  String signature = request.getHeader("X-Elli-Signature");
  String message = request.getReader().lines().collect(Collectors.joining());

  try {
    Mac mac = Mac.getInstance("HmacSHA256");
    SecretKeySpec keySpec = new SecretKeySpec(wehbookSecret.getBytes(), "HmacSHA256");
    mac.init(keySpec);

    String hash = Base64.getEncoder().encodeToString(mac.doFinal(message.getBytes()));
    return hash.equals(signature);
  } catch (NoSuchAlgorithmException | InvalidKeyException e) {
    return false;
  }
}

The preHandle method is invoked prior to the webhook callback. In this case, the handler calculates the hash using the HMAC-SHA256 algorithm and then compares it against the signature found in the X-Elli-Signature header. If the two match, we know the message originated from the Encompass Lending Platform and has not be altered.

Summary

In this tutorial, we presented a simple, yet effective way to use webhooks for real-time loan replication. The combination of batch replication and webhook provides a powerful toolkit for data synchronization.

To view the source code, please check out our GitHub repository.