Notifications

The Notifications feature is currently available as a Private Beta version.

Introduction

Notifications are a mechanism where we notify you that an event has occurred that is of interest to your application - typically in relation to a previous request you made to the API.

They are particularly useful for asynchronous events / processes, whereby the notification can proactively, and in real time, notify you that an update has occurred without the need for your application to make continuous requests to the API (polling).

An example use case of a notification is to notify you when a payment you have previously requested has been successfully initiated at the target institution.

We currently offer webhooks as the method of delivering notifications.

Accepting webhooks

Creating a webhook endpoint

Webhook notifications are delivered to your application using HTTPS. Therefore, you need to create an endpoint (URL) which will be used to receive them.

Each event you subscribe to can be received on a different endpoint, or the same one.

Receiving the notification

Notifications are sent to the target endpoint through a POST request with a JSON payload.

The notification (payload) is a common event object. This object includes identification of the eventType and the payload specific to this event type within a nested eventPayload object.

Example Event Object:

Copy
Copied
{
   "id":"2124343e-7b92-4da8-8424-52c6a7e3a56d",
   "eventType":"PAYMENT_STATUS_COMPLETED",
   "applicationId":"d60ebb6f-8935-4e58-999c-966fe6a05ef5",
   "organisationId":"41a3c16b-11f5-43fa-90ff-eff63ecb8eeb",
   "institutionId":"mock-sandbox",
   "eventPayload":{
     .....
   },
   "objectId":"PDC_35c0ab52-6cd0-4b98-ab78-9e2611151bb6",
   "consentToken":"eyJraWQiOiI3MmFmYjM5MS03MzRiLTQ4OTEtOWM4NC01OTgzODdiNmVkMWIiLCJhbGciOiJFUzI1NiJ9.eyJJTlNUSVRVVElPTiI6Im1vY2stc2FuZGJveCIsIkNPTlNFTlQiOiJmYTkxZWZmYy0yNzFiLTQ0ZGUtYmUxMC1kY2Y3ZmNiM2ZiMmQiLCJBUFBMSUNBVElPTl9VU0VSX0lEIjoidXNlcl8wLjQwNDQwOTgxODAxNzQ4MjY2IiwiVVNFUiI6Ijc1NGY0NTEzLTk2YmYtNDQyYy05MGUwLTc5OGMwNTZhNzYzNSJ9.q1lu8sfN2CfOILdyzm5949PI3quBZe0bRLZzpi-xZVBZviozXBiMXYhycigsHHeJkoC2NisBYwqfe5-GLD31aQ",
   "created":"2022-05-11T13:57:07.638Z",
   "url":"https://webhook.site/7304256a-14cb-413c-ac17-d6df48c3dc50",
   "notificationStatus":"DELIVERED"
}

Event schema

Attribute Description Optional
id Unique id for the notification No
eventType The type of event for which you are being notified No
applicationId Organisation associated with the above application No
institutionId The institution that is related to the event you are being notified about Yes
eventPayload Details the event your are being notified about.

The payload provided differs according to the eventType.

(e.g. a payment object for event type payment.status)

 No
objectId The id of of the resource that relates the notification

(e.g. the paymentId for a notification related to a payment, such as event type payment.status)
consentToken Where a consent was used by Yapily to retrieve an update from the institution, this indicates what consent was used Yes
created The time at which the notification was created No
url The url that has been provided as part of the event subscription and where the notification is delivered No
notificationStatus Delivery status of the notification
  • DELIVERED
 No

Responding to a notification

On receipt of a notification, you must promptly return a successful status code (2xx).

If a successful status code is not returned, then delivery of the notification will be retried.

Verifying that the notification was sent by Yapily

To verify that a notification was sent by Yapily, a yapily-signature header is added to the notification message with a jwt signed by us.

Within the payload of the jwt you get:

Copy
Copied
{
  "digest": "C1073039BD591D97D5991CFF6583D091AABF2005C99EC5523BE3C37EA8F6381A",
  "enc": "SHA256",
  "exp": 1647970592,
  "iat": 1647970291,
  "jti": "553a3ed6-914a-4062-b7e6-d7405bb2fb9d"
}
  1. The endpoint exposed: https://api.yapily.com/.well-known/jwks.json is used for fetching yapily public keys for verification with jwt.
  2. Inside the payload, exp (Expiration Time) and iat (Issue at) can be used to verify the time received is within range to avoid replay attack.
  3. Digest can be used to verify the notification message hasn't been tempered with.
    • Encode a received message body using the algorithm according to enc (encoding algorithm)
    • Compare the generated hash against digest if they are the same

Managing Notification Subscriptions

Subscribing to Notifications

You can subscribe to any of the event types that we provide notifications for.

To do so, the Post Event Subscription endpoint (POST /notifications/event-subscriptions) is used.

The eventTypeId details the event that is to be subscribed to and the url provides where you wish to receive the notification webhook.

Sample request:

Copy
Copied
curl -L -X POST 'https://api.yapily.com/notifications/event-subscriptions' \ 
-H 'Content-Type: application/json' \ 
-u 'APPLICATION_KEY:APPLICATION_SECRET' \ 
-d '{ 
  "eventTypeId": "payment.status.completed", 
  "notification": { 
    "type": "WEBHOOK", 
    "url": "https://i-am-a-webhook.com" 
    } 
  }'

Checking which notifications you are currently subscribed to

You can verify whether you are currently subscribed to a specific event type using the Get Event Subscriptions By Event Type Id endpoint (GET /notifications/event-subscriptions/{eventTypeId})

You can also retrieve the list of events to which you are currently subscribed using the Get Event Subscriptions endpoint (GET /notifications/event-subscriptions)

Unsubscribing from a notification event type

If you no longer wish to be subscribed to a particular event type, then you can unsubscribe using the Delete Event Subscription endpoint (DELETE /notifications/event-subscriptions/{eventTypeId}