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 connnected, 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.

V2

The email notification can contain the following fields:

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, if you want to make sure that no one can call your endpoint. Webhooks can be enabled by contacting support.

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.

V2 Webhooks

v2 event schema

{
  "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.

• Here is an example of the request body JSON

  {
    "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

Failure flow

Invitation

Invitation event type webhooks are meant to be used hand in hand with Atto Connect Invitation API product. The webhook will contain necessary information to track specific invitations through their phases.

• Here is an example of the request body JSON

  {
    "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

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

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

Example webhook POST request

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
}'