Overview

Introduction

These APIs enable ICE Mortgage Technology (ICE MT) Lenders to create a custom authentication function for receiving webhook events from ICE MT. This enforces custom authentication to validate and secure incoming webhook requests before processing them.

This feature does not replace the standard signing key validation for webhook subscriptions to verify the identity of the sender and integrity of the message upon receiving the notification. The signing keys remains the recommended best practice for lenders and partners subscribing to webhook events.

📘

PREMIUM APIs

These are premium APIs for Encompass customers only (for Lender use). Access requires special licensing entitlements. Please reach out to your ICE MT Account Team for more information.

Supported Webhook Custom Authentication Types

The API supports the following authentication types:

• OAuth2 Token (Client Credentials Flow):
  Webhook endpoint requests can be secured using an access token obtained through the OAuth2 Client Credentials flow.
• OAuth2 Token (Client Assertion using Private Key & Certificate):
  Authentication can be achieved with an OAuth2 token obtained via the Client Assertion flow, which utilizes a private key and certificate (as defined in RFC 7523).
• Custom Headers:
  Webhook requests can be authorized solely based on the presence of specific custom headers.
• Custom Headers with Token Request:
  A combination of custom headers and a token obtained through a separate request can be used for authentication.

Usage Notes

The enablement of the custom function for webhook subscriptions is a two-step process which includes the following:

1. The super administrator first creates the custom auth function using the following endpoint:
   • Create Webhook Custom Auth Function
     POST /webhook/v1/functions/auth
2. The super administrator then maps the custom auth function to the webhook subscriptions that need to follow the given custom auth policy using the following endpoint:
   • Link Custom Auth Function to Webhook Subscription
     PATCH /webhook/v1/subscriptions/{subscriptionId}/functions/auth/{functionId}

🚧

Webhook Custom Auth Migration from Legacy Implementations

Encompass Retail Customers with legacy Webhook Custom Auth implementations created prior to March 2025, previously facilitated through ICE MT PSO, must now manage their configurations via self-service by reconfiguring it through these Webhook Custom Auth APIs. Once configured through these APIs, the legacy implementation will be disabled, ensuring a smooth transition to the new Webhook Custom Auth service.