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".
Value | Definition | Auto Retry? | Manual Retry? |
---|---|---|---|
EMITTED | The state of an event after it is first sent by the BONS HTTP/S agent but before the listener has responded with a status. | NO | YES |
ACKNOWLEDGED | The state of an event when a listener responds with a 200 to the emission of an event for an asynchronous subscription. | NO | NO |
PROCESSING | The state of an event when updated by an asynchronous response from a listener. This state can be used when an event triggers complex or long-running business processes that may succeed or fail at a later time. | NO | NO |
SUCCEEDED | The state of an event when updated by an asynchronous response from a listener to indicate that downstream processing has completed successfully and that there is no need for a retry from Blend. | NO | YES |
FAILED | This state is set when a listener responds with any code outside of the 2xx range upon initial event delivery for both synchronous and asynchronous subscriptions. Note that once the Events system receives a 2xx response for the initial message delivery, subsequent asynchronous state updates to the FAILED state will not trigger retries. | YES | YES |
NO_ACTION | This state may be used if, for example, you wish to subscribe to a large set of events but only have the development bandwidth to process a smaller subset of them. You may provide a 204 response on the original call or asynchronously respond with a "NO_ACTION" state update event to halt further retries. This is an ideal solution for enabling faster iterative development. | NO | YES |
QUEUED | This state is used to denote the time between when an event is generated by one of Blend's microservices and when it is prepared and ready to be dispatched to a subscriber. During this time, no retries or alterations may be made to the event record and no updates may be posted. | NO | NO |
INVALID | This state is used to denote an invalid transmission and may be used with an asynchronous state event only. This state is not retryable and is generally not suggested for use outside of development environments. | NO | NO |
CANCELLED | This state is set by an asynchronous state event and is used to describe an event which, at some point during downstream asynchronous processing, has become unneeded. For example, if your systems are processing several disclosures-related events simultaneously and then your receive a notification that the party has declined the disclosure package, you may wish to invalidate all outstanding events to avoid retries. | NO | YES |
DISABLED | This state is set by an asynchronous state event and is used to denote that a subscriber has disable processing on a specific event class. This is a good way to gracefully deprecate the processing of certain events within your listeners without having to work with your Account Manager or Deployment Engineer. | NO | YES |
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
}
}
}
}
Updated over 3 years ago