# Vendia Notifications

Vendia Notifications provide a mechanism to integrate and monitor your production systems.

### Dead-Letter Notifications

When a given [block](https://docs.vendia.com/platform/vendia-terminology#block) is not approved by [consensus](https://docs.vendia.com/platform/vendia-terminology#consensus), each [transaction](https://docs.vendia.com/platform/vendia-terminology#transaction) in the block is not applied. This means that the transactions will not be reflected within either the [ledger](https://docs.vendia.com/platform/vendia-terminology#ledger) or [world state](https://docs.vendia.com/platform/vendia-terminology#world-state).

When using either `NODE_COMMITTED` (default) or `ASYNC` [sync mode](https://docs.vendia.com/platform/operational/scalar-data/graphql#sync-modes-for-mutations), dead-letter notifications are the only way to be notified of transactions that fail to apply. These transactions will not be reflected within either the [ledger](https://docs.vendia.com/platform/vendia-terminology#ledger) or [world state](https://docs.vendia.com/platform/vendia-terminology#world-state).

A dead-letter notification sent by a **workspace** will contain the following fields:

| Field Name       | Description                                                                                     |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| `transactionId`  | The ID of the transaction that failed to apply.                                               |
| `mutation`       | The raw form of the mutation within the transaction requiring attention.                       |
| `owner`          | The name of the **workspace** that submitted the mutation.                                     |
| `submissionTime` | The timestamp when the mutation was submitted.                                               |
| `reasonType`     | A representation of the type of error from which the notification recipient can decide how to handle the failure. Possible values include `RETRYABLE`, which indicates that the mutation should be able to be safely resubmitted. `NON_RETRYABLE` indicates that the mutation should not be resubmitted and that an operator may want to review the state of their **workspace**(s). |
| `reasonText`     | A human-readable message providing extra context for the failure.                             |

An example of what the payload of a dead-letter notification could look like:

```
{

"transactionId": "transaction_Id",

"mutation": "updateSelf_Shipment(id:\"017d1206-7881-4279-995a-e4176d8f223a\",input: {delivered: true, lastUpdated: \"2020-12-02T14:10:02Z\", location: [47.3741, -122.031]}){error}",

"owner": "shipper",

"submissionTime": "2021-11-12T16:42:50.691102+00:00",

"reasonType": "NON_RETRYABLE",

"reasonText": "Verification failure during transaction processing."

}
```

## Inbound Service Connectors

Vendia Share supports several additional inbound (“ingress”) options beyond GraphQL mutations:

- _Lambda functions and Amazon EventBridge_. You can easily use AWS Lambda functions to convert any of the dozens of AWS-provided events into GraphQL mutations, including events from S3, Aurora, and many other AWS services into transactions and then submit them to the Vendia-provided SQS queue for processing.

- _SQS queues_. Vendia automatically creates an inbound SQS queue to hold pending transactions. Vendia recommends using the GraphQL endpoint when possible because it is often easier and adds a layer of type safety; however, submitting transactions directly to SQS is supported.

- _SNS topics_. You can connect an SNS topic to the Vendia-provided SQS queue for automatic ingress via SNS.

## Outbound Service Connectors

When data in a **project** is modified, an [update is made to the ledger to capture this information](https://docs.vendia.com/platform/vendia-terminology#block), but being able to react to what’s happening within your **project**’s **workspace**(s) is a key piece of leveraging the power of Vendia Share. In order to accomplish this, each **workspace** can be configured to emit notifications upon success and failure when processing mutations.

### Block Notifications

When a given [block](https://docs.vendia.com/platform/vendia-terminology#block) has been committed to both the [ledger](https://docs.vendia.com/platform/vendia-terminology#ledger) and [world state](https://docs.vendia.com/platform/vendia-terminology#world-state), your **workspace** will emit a notification consisting of a summary of the transactions included within said block.

Let’s assume you have configured an output integration. When a new block is created, your integration receives a notification.

```
{

"blockId": "000000000000123",

"blockHash": "block_hash",

"mutations": [{ "_id": "transaction_Id", "_owner": "NodeOwner" }],

"part": 1,

"totalParts": 1

}
```

Once your integration receives a notification that a block has been created, the integration must then `query` the block. Below is a sample query that can be used to surface information about the mutation used to create the block.

```
query q {

getVendia_Block(id: "000000000000123") {

previousBlockId

blockHash

previousBlockHash

commitTime

transactions {

_id

_owner

submissionTime

mutations

}

}

}
```

This sample query will return relevant information about mutations recorded in the block.

```
{

"data": {

"getVendia_Block": {

"previousBlockId": "000000000000123",

"blockHash": "97d85748a39afc104573bf09f69fa388a5e9c6e922b9816508c8ef3ab75dfa38",

"previousBlockHash": "518d1cc60efc14645f4dd54805ab7a78ef90bd06b3e1280c2d8c111c70322cc1",

"commitTime": "2021-11-12T16:42:58.127872+00:00",

"transactions": [

{

"_id": "transaction_Id",

"_owner": "shipper",

"submissionTime": "2021-11-12T16:42:50.691102+00:00",

"mutations": [

"updateSelf_Shipment(id:\"017d1206-7881-4279-995a-e4176d8f223a\",input: {delivered: true, lastUpdated: \"2020-12-02T14:10:02Z\", location: [47.3741, -122.031]}){error}"

]

}

]

}

}

}
```

Based upon the contents of the block - the `mutations` in the list of `transactions` or perhaps the `_owner` - you can take action. What kind of action? Perhaps you need to instruct an Enterprise Resource Planning (ERP) application to release funds when a shipment is received in good order. Maybe you need to make a post to social media that an event has been scheduled by a partner. There is really no limit to what your integration can do.

### Setting Up Notifications

**Project** **workspaces** can be configured to emit events for the following subscriber types:

- HTTPS webhooks

- Email addresses

- AWS Lambda functions

- Amazon SQS queues

- Amazon Kinesis data firehoses

- Azure Functions

- Azure Queue Storage

For specifics on how to configure any of these subscribers for your **workspace**(s), see [Getting Started with Notifications](https://docs.vendia.com/platform/limited-availability/integrations/notifications).