## Notifications

Notifications are used by Atto to inform you of your customer’s user journey
through Atto. Notifications come in two flavours, email and webhook.
Notifications can be used to track the customer's status e.g. whether they
have successfully connected, their data is available, an invitation email
has been delivered, etc. Notifications also include any errors that may have
occurred.

Different notifications can be set up for different `providerAuthentication`
and `dataAvailability` statuses.

### Email

Email notifications are useful for Dashboard product consumers, who are not
utilizing Atto APIs. These notifications will give you real-time info about
connected consent details.

The email notification can be enabled by [contacting
support](https://www.atto.co/about/contact).

details
summary
h3
V1 (deprecated)
*NB: Email notifications are supported for v1 notifications only.*

The email notification can contain the following fields:

| Parameter | Description |
|  --- | --- |
| ConsentId | Unique ID for the end-user's Consent that allows us to fetch their data |
| CustomerReference | Your reference for the end-user |
| ProviderAuthentication | The provider authentication status for the consent: Success, Error |
| DataAvailability | The data availability status for the consent. Populated when Provider Authentication is successful, otherwise null: Error, Partial, Complete, Processed |
| ErrorMessage | The error message if there are any errors raised for this event (Optional) |


### V2

The email notification can contain the following fields:

| Parameter | Description |
|  --- | --- |
| ConsentId | Unique ID for the end-user's Consent |
| Consent Status | Consent current status  Possible values: `"Pending"` `"Active"` `"Revoked"` `"Abandoned"`  `"Failed"` `"Expired"` `"UpcomingExpiration"` |
| Journey Type | Refers if end-user is going through process to extend consent validity.  Possible values: `"Reconfirmation"` `"Reauthentication"`  **(Optional)** In case of a new connection, Journey Type is not populated |
| Consent Period | Consent start date, Consent end date |
| Last Updated | Date when Consent status was last time updated |
| CustomerReference | Your reference for the end-user |
| Data Availability | The data availability status for the consent.  Possible values: `"Error"` `"Partial"` `"Complete"` `"Processed"`  **(Optional)** We are populating this field only if Consent Status is `"Active"` |
| Error Message | The error message if there are any errors raised for this event.  **(Optional)** We are populating this field only if there have been any errors |


### Webhooks

Atto uses webhooks to send real-time notifications to your application
regarding updates to a user consent within the Atto platform. These webhooks
deliver push notifications through HTTPS requests with the data encapsulated
in JSON payloads.

#### Configuring webhooks

To use webhooks, you will first need to set up an endpoint that accepts HTTP
POST requests with the schema defined below. It is possible to apply [OAuth2
authentication](#Optional-OAuth2-Authentication), if you want to make sure
that no one can call your endpoint. Webhooks can be enabled by [contacting
support](https://www.atto.co/about/contact).

#### Payload Details

- The HTTP Method will always be `POST`
- The Content Type will always be `application/json`


#### Retry policy

If your endpoint is not able to handle the first webhook, then we will retry
three times before discarding it. There will be 2 seconds, 4 seconds and 8
seconds delay between retries.

details
summary
h3
V1 (deprecated)
The webhook will contain your unique ID `customerReference` passed back to
you as well as our internal reference `consentId`. The internal reference is
required to access any of our endpoints about that individual.

- You will need to set up an endpoint
- This endpoint must be able to accept a post request from our server as defined below.


#### Payload Details

- The HTTP Method will always be `POST`
- The Content Type will always be `application/json`
- The request JSON will have the following properties:


| Property | Type | Nullable | Details |
|  --- | --- | --- | --- |
| consentId | `string` | No | Unique ID for the end-user's Consent that allows us to fetch their data |
| applicationId | `string` | No | The ID of your account in our system |
| customerReference | `string` | Yes | Your reference for the end-user |
| providerAuthentication | `string` Enum: `"Success"`, `"Error"` | No | The provider authentication status for the consent |
| dataAvailability | `string` Enum: `"Error"`, `"Partial"`, `"Complete"`, `"Processed"` | Yes | The data availability status for the consent. Populated when Provider Authentication is successful, otherwise null |
| paymentConfirmation | `string` Enum: `"Complete"`, `"Incomplete"` | Yes | The payment confirmation status for the consent. Populated when Payment Confirmation is enabled |
| reauthentication | `boolean` | No | Indicates whether the consent is being re-authenticated |
| errorMessage | `string` | Yes | The error message if there are any errors raised for this event |


- Given below is a brief explanation of all the enums mentioned above
  - providerAuthentication
| Value | Explanation |
|  --- | --- |
| `"Success"` | Provider authentication was successful |
| `"Error"` | There was an error during provider authentication |
  - dataAvailability
| Value | Explanation |
|  --- | --- |
| `null` | Data availability status is pending |
| `"Error"` | There has been an error in fetching data from the provider |
| `"Partial"` | Account data is available from Data API, however transaction data is still pending |
| `"Complete"` | The bank data is avaiable via the Stored Data API and Data API |
| `"Processed"` | Stored Data has been enriched and is avaiable via the Stored Data API |
  - paymentConfirmation
| Value | Explanation |
|  --- | --- |
| `null` | Payment account confirmation is not available/enabled |
| `"Complete"` | Payment account confirmation was completed |
| `"Incomplete"` | Payment account confirmation is incomplete |
- Here is an example of the request body JSON

```javascript
{
  "consentId": "207e50aa-72c0-11eb-9439-0242ac130002",
  "applicationId": "26e667b6-72c0-11eb-9439-0242ac130002",
  "customerReference": "defaultuser",
  "providerAuthentication": "Success",
  "dataAvailability": "Complete",
  "paymentConfirmation": null,
  "reauthentication": false,
  "errorMessage": null
}
```


### V2 Webhooks

#### v2 event schema

| Property | Type | Nullable | Details |
|  --- | --- | --- | --- |
| eventId | `string` | No | Unique ID belonging to the Webhook event |
| eventType | `string` Nominally: `"Consent"` `"Invitation"` | No | Indicates the type of event the webhook represents |
| eventTime | `string`UTC formatted timestamp | No | Indicates the time when the webhook was sent |
| schemaType | `string`Nominally: `"Consent"` `"Email"` | No | Indicates the webhook schema type |
| schemaVersion | `string` | No | Indicates the version of the webhook schema |



```javascript
{
  "eventId": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
  "data": {  },
  "eventType": "Consent",
  "eventTime": "2022-01-01T00:00:00Z",
  "schemaType": "Consent",
  "schemaVersion": "1.0.0"
}
```

#### Consent

Consent schema returns a holistic overview of consent status and data
availability, and provides details about connected provider, consent
validity period and its journey type.

**Configuring this Webhook is highly recommended in case you are using Atto
APIs.**

| Property | Type | Nullable | Details |
|  --- | --- | --- | --- |
| consentId | `string` | No | Unique reference for the consent |
| applicationId | `string` | No | Unique ID of your account in our system that was used to request the Connect Invitation |
| providerId | `integer` | No | Provider Id for the consent |
| providerName | `string` | Yes | Provider name for the consent |
| configurationName | `string` | Yes | Specific configuration of the client |
| customerReference | `string` | No | Your reference for the end-user |
| consentStatus | `string` Enum: `"Pending"` `"Active"` `"Revoked"` `"Abandoned"` `"Failed"` `"Expired"` `"UpcomingExpiration"` | No | Consent status |
| consentJourney | `string` Enum: `"Reauthentication"` `"Reconfirmation"` | Yes | Indicates which journey type the end-user went through |
| consentStart | `string` UTC formatted timestamp | Yes | Start date for the consent |
| consentEnd | `string` UTC formatted timestamp | Yes | End date for the consent |
| statusUpdated | `string` UTC formatted timestamp | No | Date of last status update of the consent |
| dataAvailability | `string` Enum: `"Error"` `"Partial"` `"Complete"` `"Processed"` | Yes | The data availability status for the consent  **(Optional) We are populating this field only if `consentStatus` is `Active`** |
| errorMessage | `string` | Yes | The error message if there are any errors raised for this event |
| invitationId | `string` | Yes | Unique ID belonging to a particular Connect Invitation |
| eventType | `string` Nominally: `"Consent"` | No | Indicates the type of event the webhook represents |
| eventTime | `string`UTC formatted timestamp | No | Indicates the time when the webhook was sent |
| schemaType | `string`Nominally: `"Consent"` | No | Indicates the webhook schema type |
| schemaVersion | `string` | No | Indicates the version of the webhook schema |


- Here is an example of the request body JSON

```javascript
{
  "eventId": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
  "data": {
  "consentId": "e521cf62-a45f-49c5-8372-94853fffeb55",
  "applicationId": "97ab27fa-30e2-43e3-92a3-160e80f4c0d5",
  "providerId": 0,
  "providerName": "string",
  "configurationName": "string",
  "customerReference": "string",
  "consentStatus": "Pending",
  "consentJourney": "Reconfirmation",
  "consentStart": "2019-08-24T14:15:22Z",
  "consentEnd": "2019-08-24T14:15:22Z",
  "statusUpdated": "2019-08-24T14:15:22Z",
  "dataAvailability": "string",
  "invitationId": "string"
  },
  "eventType": "Consent",
  "eventTime": "2022-01-01T00:00:00Z",
  "schemaType": "Consent",
  "schemaVersion": "1.0.0"
}
```


#### Consent event flow

##### Success flow

![Consent event success
flow](/assets/notification-webhook-consent-success-flow.da71a62b158875307ee87e4b4027db32207ea6b3371b9903773968ea3c075252.d5e2313b.png)

##### Failure flow

![Consent event failure
flow](/assets/notification-webhook-consent-failiure-flow.52273b30a1f1394e2debee4ad4a191bede45e82865f27b7d23d310a40544b3de.d5e2313b.png)

#### Invitation

Invitation event type webhooks are meant to be used hand in hand with [Atto
Connect Invitation API](/content/apis/connect-invitation) product. The webhook will
contain necessary information to track specific invitations through their
phases.

| Property | Type | Nullable | Details |
|  --- | --- | --- | --- |
| eventId | `string` | No | Unique ID belonging to the Webhook event |
| invitationId | `string` | No | Unique ID belonging to a particular Connect Invitation |
| emailState | `string` Enum: `"Sent"` `"Received"` `"Opened"` `"Clicked"` `"Failed"` | No | Indicates state of email |
| customerReference | `string` | No | Your reference for the end-user |
| smtpErrorCode | `string` | Yes | Indicates the SMTP error code (if any) |
| smtpErrorMessage | `string` | Yes | Indicates the SMTP error reason (if any) |
| applicationId | `string` | No | Unique ID of your account in our system that was used to request the Connect Invitation |
| connectionStatus | `string` Enum: `"Pending"` `"Active"` `"Revoked"` `"Abandoned"` `"Failed"` `"Expired"` | No | Indicates if the end-user has actioned Connect Flow |
| eventType | `string` Nominally: `"Invitation"` | No | Indicates the type of event the webhook represents |
| eventTime | `string`UTC formatted timestamp | No | Indicates the time when the webhook was sent |
| schemaType | `string`Nominally: `"Email"` | No | Indicates the webhook schema type |
| schemaVersion | `string` | No | Indicates the version of the webhook schema |


- Here is an example of the request body JSON

```javascript
{
  "eventId": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
  "data": {
  "invitationId": "fdd86d02-5745-4cc9-ad9a-8372d6ec2c9b",
  "applicationId": "26e667b6-72c0-11eb-9439-0242ac130002",
  "emailState": "Received",
  "customerReference": "ProposalNumber",
  "smtpErrorCode": "",
  "smtpErrorMessage": "",
  "connectionStatus": "Pending",
  },
  "eventType": "Invitation",
  "eventTime": "2022-01-01T00:00:00Z",
  "schemaType": "Email",
  "schemaVersion": "1.0.0"
}
```


### Optional OAuth2 Authentication

If you want to make sure that no one can call your endpoint, except for
verified clients, we can enable our server to connect to your OAuth2
authorisation server and get an access token. We then send it to you to
authenticate you to use our API, in the same way that you connected to our
OAuth2 provider. In addition to the data listed above, we will require the
following details:

- A Client ID for your OAuth authorisation server
- A Secret Key for your OAuth authorisation server
- An endpoint to request the access Token
- An optional scope


#### Example requests

Here are two example requests we do to compete the OAuth2 Webhook flow:

- Make a request for bearer token using the customer supplied: Authorisation
Server Url, Client Id, Client Secret, and Optional Scope which returns the
accessToken that we use to authenticate with their webhook URL. We use
`Basic` authentication so the request will contain a header of the form
`Authorization: Basic <encodedCredentials>` where encodedCredentials is a
Base64 encoded `ClientId:ClientSecret`
- We call the customer supplied Webhook Url using the access token returned
as the bearer token


##### Example initial token request


```bash
curl --location -g --request POST 'https://[CustomerAuthorisationServerUrl]' \
--header 'Authorization: Basic W0NsaWVudElkXTpbQ2xpZW50U2VjcmV0XQ==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=[Optional Scope]'
```

##### Example expected response


```javascript
{
  "token_type": "bearer",
  "expires_in": 123,
  "access_token": "ReturnedAccessToken"
}
```

##### Example webhook POST request


```bash
curl --location -g --request POST 'https://[CustomerWebhookUrl]' \
--header 'Authorization: Bearer [ReturnedAccessToken]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "consentId": "207e50aa-72c0-11eb-9439-0242ac130002",
  "applicationId": "26e667b6-72c0-11eb-9439-0242ac130002",
  "customerReference": "defaultuser",
  "providerAuthentication": "Success",
  "dataAvailability": "Complete",
  "paymentConfirmation": null,
  "reauthentication": false,
  "errorMessage": null
}'
```