How to set up webhooks and connect them with DigiFi.

Overview

To begin receiving and processing webhook events from DigiFi, follow these steps:

  1. Identify the type(s) of events you want to listen for.
  2. Create a webhook endpoint as an HTTP endpoint (i.e. URL) on your local server.
  3. Parse event objects sent by DigiFi and return 2xx response status codes.
  4. Deploy your webhook endpoint to a publicly accessible HTTPS URL.
  5. Connect your HTTPS URL to DigiFi's platform in the DigiFi Webhooks UI.

Step 1: Identify Which Events You Want To Monitor

A single webhook endpoint can listen for one or multiple types of events and DigiFi's platform emits the following types of events:

Event Type

Description

application.created

Occurs when applications are created.

application.updated

Occurs when applications are updated.

application.deleted

Occurs when applications are deleted.

borrower.created

Occurs when borrowers are created.

borrower.updated

Occurs when borrowers are updated.

borrower.deleted

Occurs when borrowers are deleted.

intermediary.created

Occurs when intermediaries are created.

intermediary.updated

Occurs when intermediaries are updated.

intermediary.deleted

Occurs when intermediaries are deleted.

document.created

Occurs when documents are created.

document.updated

Occurs when documents are updated.

document.deleted

Occurs when documents are deleted.

note.created

Occurs when notes are created.

note.updated

Occurs when notes are updated.

note.deleted

Occurs when notes are deleted.

task.created

Occurs when tasks are created.

task.updated

Occurs when tasks are updated.

task.deleted

Occurs when tasks are deleted.

👍

Best Practice: Only Listen For Relevant Events

Your webhook endpoints should be configured to receive only the types of events required by your integration. Listening for extra events (or all events) will put undue strain on your server and is not recommended.

You can change the events a webhook endpoint will receive by navigating to an endpoint within the DigiFi platform.


Step 2: Create A Webhook Endpoint On Your Local Server

Set up an HTTP endpoint on your local machine that can accept unauthenticated webhook requests with a POST method.

For example, this is a route written in Express (Node.js). The /webhooks route is configured to accept only POST requests and expects data to be delivered in a JSON payload.

const express = require('express');

const app = express();

app.post('/webhooks', (req, res) => {
  res.status(200).send({});
});

app.listen(3000, () => {
  console.log(`Example app listening at http://localhost:3000`)
});

Step 3: Parse Event Objects And Return 2xx Responses

Your endpoint must be configured to read event objects for the type of event notifications you want to receive. DigiFi sends events to your webhook endpoint as part of a POST request with a JSON payload.

Check Event Objects

Each event is structured as an event object with a eventId, eventType and related event data nested under the data. Your endpoint must check the event type and parse the payload of each event.

Within the data section, there are two main subsections:

  • previousObject provides the data prior to the change that triggered the event.
  • object provides the updated data (after the change that triggered the event).

These subsections only appear if relevant. For example, in a application.created event only object will appear, but in an application.updated event both previousObject and object``` will appear.

{
  "eventId": "619r70gb56df8c78wfcb0c",
  "eventType": "application.updated",
  "createdAt": 1633887337,
  "data": {
    "previousObject": {...},
    "object": {...}
}

By comparing the information within previousObject and object, you can identify which field(s) changed
as well as the information, both before and after the change.

Return A 2xx Response

Your endpoint must quickly (within 6 seconds) return a successful status code (2xx) prior to any complex logic that could cause a timeout. For example, you must return a 200 response before running another integration within the DigiFi platform.

const express = require('express');

const app = express();

app.post('/webhooks', (req, res) => {
  switch (req.body.eventType) {
    case 'application.created': {
      handleApplicationCreate();
    }
    case 'application.updated': {
      handleApplicationUpdate();
    }
  }

  res.status(200).send({});
});

app.listen(3000, () => {
  console.log(`Example app listening at http://localhost:3000`)
});

Built-In Retries

DigiFi webhooks have built-in retry methods for failed requests:

Retry Number

Timing

1

5 minutes after the actual request

2

15 minutes after the prior retry

3

30 minutes after the prior retry

4

1 hour after the prior retry

5

2 hours after the prior retry

6

4 hours after the prior retry

7

8 hours after the prior retry

After several hours, we will:

  • Email all users with permission level of Owner, as well as the users the created and most recently updated the endpoint in DigiFi's platform.
  • Automatically disable the endpoint (if you haven’t addressed the issue).

Handling Duplicate Events

Your webhook endpoints might occasionally receive the same event more than once. You can guard against duplicate events by logging the eventId of events you’ve processed, and then checking future events against this.


Step 4: Deploy Your Endpoint To A Public HTTPS URL

To begin receiving events from DigiFi, you must deploy your endpoint to a publicly accessible HTTPS URL.

👍

Receive Events With An HTTPS Server

If you use an HTTPS URL for your webhook endpoint, DigiFi validates that the connection to your server is secure before sending your webhook data. For this to work, your server must be correctly configured to support HTTPS with a valid SSL certificate.


Step 5: Register Your Public URL In DigiFi's Webhooks Dashboard

Once you've deployed your endpoint to a public HTTPS URL, you can add the endpoint to DigiFi's platform through our webhooks dashboard.

To add an endpoint to DigiFi's platform:

  • Navigate to Company Settings > Developers > DigiFi Webooks
  • Click the Add Endpoint button

This will open a form with the following information:

Field

Description

URL

The public HTTPS URL your endpoint was deployed to.

Description

A brief description of your webhook.

Listening For

The event(s) that your endpoint will listen for.

Status

A toggle to decide whether your endpoint should immediately be activated (if not, you can activated it later).

Once you have completed the form, click Add Endpoint. Your endpoint will be created and you'll begin receiving events immediately if your endpoint was activated.

You will be able to see all events related to this endpoint in the "Events" tab, and the "Integration" tab provides your Webhook Secret Key, which you can use to further secure your endpoint (suggested).