Product Registration

One of the first things you need to when beginning to develop an integration on EPC, is to register an instance of your integration application with the EPC platform. This is done by invoking the POST HTTP operation on the https://api.elliemae.com/partner/v2/products resource.

An EPC product resource represents an instance of a partner application. Its data model encapsulates the various pieces of information that govern an application on the EPC platform. For example:

Environment and Status

Whether the instance is still in development and is only meant to serve sandbox/test transactions, or whether it has been approved to serve production transactions
Listing Information

How the partner integration is listed across the Encompass application suite
Routing Information

Where the application's user-interface is located and where it listens for webhook notifications
Credential Information

The credentials the application expects from Lenders and their users
Entitlements

The loan data an application is allowed to read and write to, and the instances of a specified Encompass product that are allowed to access the application

The example below shows how to create a new instance of an EPC product with basic configuration information (which will later be enhanced). In the sample EPC Postman collection provided, find the Create a New Product request in the Product Registration and Management folder. The product configuration options are to be supplied as JSON in the body of the request, as done below:

{
  "name": "{{product_name}}",
  "listingName": "{{product_listing_name}}",
  "interfaceUrl": "{{product_interface_url}}",
  "requestTypes": [
    "{{request_type}}"
  ],
  "tags": {
    "applications": [
      "LO Connect"
    ],
    "categories": [
      "{{service_category}}"
    ],
    "workflows": [
      "interactive"
    ]
  },
  "webhooks": [
    {
      "resource": "urn:elli:epc:transaction",
      "events": [
        "created",
        "updated"
      ],
      "signingkey": "TSuO$cRRSasmVr5RnQ8cqIkx^ugRFhOzI^bNGRwbu5P7B",
      "url": "{{webhook_url}}"
    },
    {
      "resource": "urn:elli:epc:transaction:event",
      "events": [
        "created"
      ],
      "signingkey": "TSuO$cRRSasmVr5RnQ8cqIkx^ugRFhOzI^bNGRwbu5P7B",
      "url": "{{webhook_url}}"
    }
  ],
  "credentials": [
    {
      "id": "username",
      "type": "string",
      "title": "Username",
      "secret": false,
      "required": true,
      "scope": "user"
    },
    {
      "id": "password",
      "type": "string",
      "title": "Username",
      "secret": true,
      "required": true,
      "scope": "user"
    },
    {
      "id": "organizationId",
      "type": "string",
      "title": "Organization ID",
      "secret": false,
      "required": true,
      "scope": "company"
    }
  ]
}

EPC product endpoints support the JSON merge specification for the PATCH operation that updates the product configuration, so not all these options have to be supplied in the first call. An iterative approach can be used for product registration: first register a product with minimal configuration options, then add configuration options in consequent calls.

Webhook Subscriptions and User Interface URL

To register a product, at least one backend webhook listener is required to be active and be able to receive transaction events. The webhook URL is the address of a web server that will receive the webhook event payloads sent to your product. The server can then take action based on the content of the payload. You should choose a web server that's appropriate for the volume of webhook traffic that your product will encounter.

The product's user-interface can also be served from a local machine or a hosted and publicly available endpoint during development/testing.

Choosing a webhook URL for development and testing

While you develop and test your app, you can use a webhook payload delivery service like Smee to capture and forward webhook payloads to your local development environment. Never use Smee for an application in production, because Smee channels are not authenticated or secure. Alternatively, you can use a tool like localtunnel, or the Hookdeck Console that exposes your local machine to the internet to receive the payloads.

Creating a webhook URL with Smee

You can use Smee to create a unique domain where GitHub can send webhook payloads, without exposing your local development to the internet. Smee calls this unique domain a "Webhook Proxy URL." You can use Smee's Webhook Proxy URL as the webhook URL for your GitHub App.

1- To use Smee to create a unique domain, go to https://smee.io and click Start a new channel.
2- On the Smee channel page, follow the instructions under "Use the CLI" to install and run the Smee client.
3- To connect your Smee webhook URL to your product, use your unique Smee domain in the "Webhook URL" field of your product.

Webhook Signing Key

When subscribing for transactional webhooks, partners need to provide a shared secret signingkey - used by the EPC platform to generate a SHA256 hash-based message authentication code (HMAC) to deliver to partners as part of their webhook notifications. This key needs to be between 32 and 64 characters long, contain at least one upper case letter, one lower case letter, one number, and one character from this list: ! @ # $ ^ *.

Partner applications must use this signingkey to verify the integrity of the webhooks they receive - by calculating their own SHA256 HMAC signature of the webhook request body and comparing it with the Elli-Signature webhook request header - containing the signature the EPC platform calculated upon webhook egress. This verification process is described in more detail in the section on working with webhooks.

After the webhook listener and signingkey are created, the transaction webhook subscription can be registered by invoking the https://api.ellieme.com/partner/v2/products partner REST API endpoint. Update the request JSON body in Postman and click the Send button.

{
    "name": "ZipRight",
    "listingName": "Zipcode Validator",
    "interfaceUrl": "https://3d5e2d38.yourserver.io",
    "requestTypes": [
        "ZIP Code Validation"
    ],
    "webhooks": [
        {
            "resource": "urn:elli:epc:transaction",
            "events": [
                "created",
                "updated"
            ],
            "signingkey": "SWITCH_THIS_WITH_YOUR_HMAC_KEy1@",
            "url": "https://db0a1b1c.yourserver.io"
        }
    ]
}

The following response from EPC indicates successful registration:

{
    "id": "562a9740-2e27-44fd-8ff6-8731de6aa0fc",
    "partnerId": "YOUR_PARTNER_ID",
    "name": "ZipRight",
    "listingName": "Zipcode Validator",
    "requestTypes": [
        "ZIP Code Validation"
    ],
    "environment": "sandbox",
    "status": "development",
    "interfaceUrl": "https://3d5e2d38.yourserver.io",
    "integrationType": "ASYNC",
    "entitlements": {
        "access": {
            "allow": [],
            "deny": []
        },
        "data": {
            "origin": {
                "fields": []
            },
            "transactions": [],
            "created": "2019-11-18T23:57:14Z",
            "createdBy": "urn:elli:partner:007001:environment:test",
            "extensionCount": 0
        }
    },
    "webhooks": [
        {
            "subscriptionId": "b8fb8b38-22b4-46a5-b019-418c1fa61a7b",
            "url": "",
            "events": [
                "created",
                "updated"
            ],
            "resource": "urn:elli:epc:transaction"
        }
    ],
    "created": "2019-11-18T23:57:14Z",
    "createdBy": "urn:elli:partner:007001:environment:test"
}

The next section illustrates how to add more configuration options to the registered product.