Event Structure

Event Definition

Events represent actionable changes in Blend's data and are emitted to allow external integrators to build fully-functioned near-real-time integrations in conjunction with Blend's APIs.

Event Types

Blend emits three types of events: Data Model Driven, Conditional, and System.

Data Model Driven Events

These events represent a change--creation, update, or deletion--of a specific instance of one of Blend's data entities (e.g. an application, a party, etc.). They contain information specific to the changed entity as well as, in some cases, references to other associated entities. These comprise the majority of all Blend events.

Conditional Events

These events fire when a compound condition--usually solution-specific--is reached in the Blend system. The primary difference between a Data Model Driven Event and a Conditional Event is that the latter depends on complex changes across entities (e.g. TRID being triggered for a mortgage application or eConsent being provided or rejected by a party to an application).

System Events

These events are triggered to help coordinate the smooth delivery of events between systems and include, for example, a heartbeat health-check event. These events are specific to your implementation and may not be needed for most implementations.

Event Structure

All event types are formed from augmenting a common base message. Depending on the event type as described above, keys may be added or subtracted where appropriate. Specific event examples are provided in the Events Schemas & Definitions section of this guide.

Base Event

All events have a minimal set of required fields and most also have optional fields. Optional fields are discussed in detail in the Event Schemas & Definitions section of this guide on a per-event basis.

id

Type: String UUID
Required: TRUE
Example: d5ecd604-137e-4f10-8ac7-9f3214bb4aa4

An event's "id" is guaranteed to be unique across all Blend products within a particular environment (e.g. production environments vs. testing and development environments). This value will be a string UUID.

firstEmittedAt

Type: ISO8601 DateTime String
Required: TRUE
Example: 2019-01-16T16:51:16.661Z

The time at which the event was first emitted from Blend's system to a configured subscriber. This time is set at the time of first emission and remains constant across retries, allowing you to determine, for example, how long an event has been retrying.

This timestamp is used for event coordination and, if enabled for your solution, reconciliation processes (such as event replay). All times are provided in UTC with the timestamp identifier Z as described in the ISO8601 standard.

lastEmittedAt

Type: ISO8601 DateTime String
Required: TRUE
Example: 2019-01-16T16:51:16.661Z

The time at which the event was most recently emitted from Blend's system to a configured subscriber. This time represents the current retry and is distinct from the firstEmittedAt timestamp, allowing you to determine, for example, how long an event has been retrying.

This timestamp is used for event coordination and, if enabled for your solution, reconciliation processes (such as event replay). All times are provided in UTC with the timestamp identifier Z as described in the ISO8601 standard.

attempt

Type: Integer
Required: TRUE
Example: 1

An integer that represents the number of times Blend has attempted to deliver the event.

status

Type: String
Required: TRUE
Example: SUCCEEDED

A string representing the state of the event in the processing lifecycle. There is a fixed set of states available, but adding new states is not considered a breaking change and should be accepted. All values are "UPPERCASE" and, where more than one word is used, connected by underscores, e.g. "TWO_WORDS".

data

Type: JSON Object
Required: FALSE
Example:

{
  "id": UUID
  "type": String
  "action": String
  "solution": String
  "trigger": {
    "type": String
    "triggeredAt": ISO8601 DateTime String
    "metadata": Object // Optional
  },
  "fields": {
    "keyName": {
      "value": String
      "metadata": Object // Optional
      "links": LinkObject // Optional
    }
  }
}

The data object is used to contain the majority of information related to an event's referenced entity or trigger. The fields key points to an array of objects, each containing a field that was altered by the data event that caused this event to be emitted by Blend.

trigger

This attribute is included if the event is a Conditional Event and will contain the trigger type, the ISO8601 DateTime of the time that the trigger was emitted, and an optional metadata object that will be defined in the Events Schemas & Definitions section for each specific event type if applicable. Note that this key is optional and will not be included in any Data Model Driven Events.

fields

The "fields" attribute oi

links

Type: JSON:API Link Object
Required: FALSE
Example:

// Format
"links": {
    StringKey: { // Key name may be any valid string.
    href: URI,
    meta: {
        StringKey: String | Integer // Key name may be any valid string.
    }
  }
}

// Example
"links": {
  "parties": {
    "href": "https://api.beta.blend.com/applications/:id/parties",
    "meta": { // Optional
      "count": 10 // Optional
    }
  }
}

Link objects, where are optionally included, are specified by the JSON:API standard. These links, when included, point to a GET operation that will return a singleton or a list of entities at the listed resource as related to the primary entity described by the event (e.g. the event may describe an application being submitted and include a reference to parties associated with that application). As described in the standard:

"Where specified, a links member can be used to represent links. The value of each links member MUST be an object (a “links object”).

Each member of a links object is a “link”. A link MUST be represented as either:

• a string containing the link’s URL.
• an object (“link object”) which can contain the following members:
  • href: a string containing the link’s URL.
  • meta: a meta object containing non-standard meta-information about the link."

📘

Attribute Order

Please note that the order of attributes for all Blend Schemas, Events and APIs is NOT guaranteed!

When we combine all of the above, we arrive at the following example:

{
  "id": UUID
  "firstEmittedAt": ISO8601 DateTime String
  "lastEmittedAt": ISO8601 DateTime String
  "attempt": Integer
  "status": String
  "data": {
    "id": UUID
    "type": String
    "action": String
    "solution": String
    "trigger": {
      "type": String
      "triggeredAt": ISO8601 DateTime String
      "metadata": Object // Optional
    },
    "fields": {
      "keyName": {
        "value": String
        "metadata": Object // Optional
        "links": LinkObject // Optional
      }
    }
  },
  "links": {
    "parties": {
        "href": "https://api.beta.blend.com/applications/:id/parties",
        "meta": { // Optional
        "count": 10 // Optional
        }
    }
  }
}