Download Postman Collection
Release Notes
Back to All

HIDE - Webhook Best Practices: Event Reconciliation and More

September 11th, 2020

September 22, 2020 | Jamie Brooks

Today, we are happy to announce the general availability of Webhook Event History API, a purpose-built API that provides a synopsis of your webhook activity, including event generation, subscription matching, and notification delivery. The event history simplifies reconciliation and troubleshooting. You can use this API to identify misconfigured subscriptions and undelivered notifications.

What are Webhooks?

Webhooks enable the ICE Mortgage Technology Digital Lending Platform to deliver real-time updates to your application. Notifications are triggered when a particular event occurs and then pushed to your application via POST requests.

To create a webhook subscription, you must specify a scope and endpoint. A scope consists of a resource (e.g. loan) plus one or more related events (e.g. change), and an endpoint is a HTTPS URL to which notifications are sent. For loan change subscriptions, you must also specify an attribute filter, which is an array of loan fields expressed as JSON pointers; at least one of these fields must change for a notification to be triggered.

The following HTTP request creates a loan change subscription:

POST /webhook/v1/subscriptions
Authorization: Bearer 0007S...vg6g6
Content-Type: application/json; charset=utf-8
{
  "resource": "Loan",
  "events": [ "change" ],
  "endpoint": "https://webhook.yourcompany.com/loan/change",
  "signingkey": "zJW4r..[omitted for brevity]..StPm*",
  "filters": {
    "attributes": [
      "/applications/*/borrower/lastName",
      "/applications/*/borrower/firstName"
    ]
  }
}

A webhook notification contains sufficient detail to be actionable without exposing sensitive data. The following is an example of a webhook notification: 

POST /loan/change
Elli-Signature: neJXy..[omitted for brevity]..Mymw=
Elli-Environment: prod
Elli-SubscriptionId: 2ce07173-ecac-451b-82c3-32a4e2ed6b28
Content-Type: application/json; charset=utf-8

{
  "eventId": "42d21f-852c-4831-ad6e-38bf305bc75b",
  "eventTime": "2020-04-09T17:04:06.413Z",
  "eventType": "Change",
  "meta": {
    "userId": "jsmith",
    "instanceId": "BE12345678",
    "resourceId": "54553bb1-867b-4cc3-a39a-726e73e48c65",
    "resourceType": "Loan",
    "resourceRef": "/encompass/v3/loans/54553bb1-867b-4cc3-a39a-726e73e48c65"
  }
}

If the ICE Mortgage Technology Digital Lending Platform is unable to deliver a notification to the registered endpoint or the endpoint fails to acknowledge the notification, redelivery will be attempted. If the notification is not delivered after four attempts, it is discarded.
The following situations are considered a failed delivery attempt: a server error (i.e. a 5XX status code), an invalid response, a request timeout (i.e. no response within 30 seconds), and a connection error.

Verifying Signatures

Each webhook notification includes the X-Elli-Signature response header, which is generated using the HMAC algorithm and your signing key. To verify the origin and integrity of a notification, compute the digest and compare it to the value in the X-Elli-Signature header. If they match, then you are free to process the notification; otherwise, discard it and report the incident to ICE Mortgage Technology.

The following C# code snippet computes the HMAC digest:

var encoding = new System.Text.ASCIIEncoding();

byte[] keyByte = encoding.GetBytes(secret);
byte[] messageBytes = encoding.GetBytes(message);
            
using (var hmacsha256 = new HMACSHA256(keyByte))
{
   byte[] hash = hmacsha256.ComputeHash(messageBytes);
   return Convert.ToBase64String(hash);
}

To improve security even further, practice good key hygiene: use strong keys, protect your keys from unauthorized disclosure, and rotate the keys on a regular basis.

Detecting Duplicates

To detect duplicate notifications, you should check the event ID. Each notification includes a unique event ID, so if you encounter an ID more than once, you can be sure that it is a duplicate.

Reconciling Events

Since the delivery of webhook notifications is not guaranteed, you should implement a reconciliation process to periodically fetch data from the Event History API and look for misconfigured subscriptions and undelivered notifications.

With the Webhook Event History API, you can query events by resource, event, status, time range, and event ID. Currently, there are three types of status for events.

  • EventReceived. Indicates the event was received from the origin (e.g. Encompass)
  • SubscriptionMatch. Indicates the event was matched against one or more subscriptions
  • NotificationDelivered. Indicates a notification was successfully delivered and acknowledged

Common configuration problems include omitting required fields from an attribute filter and inadvertently creating duplicate (i.e. multiple subscriptions with the same scope) or redundant subscriptions (i.e. multiple subscriptions with overlapping scopes).

To identify an undelivered notification, check for DeliveryAttempted status of events.
A DeliveryAttempted status is logged only when there is failure from the subscription webhook endpoint. Check DeliveryAttempted statusDetails for an error response code and error response details from the subscription webhook endpoint.

Attempting delivery for Event ID 5f751949-ef0b-45ba-86bb-34041a76d825 at 
Endpoint: https://encompass-webhook.rosewood.com/loan 

Response:

"statusCode": 500,
  "headers": {
    "content-type": "application/json",
    "content-length": "36",
    "connection": "close",
    "date": "Wed, 21 Oct 2020 02:00:00 GMT",
    "x-amzn-requestid": "6f823575-1fe6-4e2f-904f-c7be96c1a845",
    "x-amzn-errortype": "InternalServerErrorException",
    "x-amz-apigw-id": "UvRlAE4foAMFkHQ=",
    "x-cache": "Error from cloudfront",
    "via": "1.1 666fd8d94e12b16d3a6998ad643580ce.cloudfront.net (CloudFront)",
    "x-amz-cf-pop": "ORD50-C1",
    "x-amz-cf-id": "lf7VL1nOya48L23MFWGQLIRQ8gLg4L0eH81YEQjqvluorzmeZprp2w=="
  },
  "body": "{\"message\": \"Internal server error\"}"
}

Get Started

The new Webhook Event History API is available with the Encompass Developer Connect 20.1 September Service Pack release. Start using the Webhook Event History API today!

© ICE Mortgage Technology, Inc. All rights reserved. Terms of Use