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:
{
"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
|
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:
{
"digest": "C1073039BD591D97D5991CFF6583D091AABF2005C99EC5523BE3C37EA8F6381A",
"enc": "SHA256",
"exp": 1647970592,
"iat": 1647970291,
"jti": "553a3ed6-914a-4062-b7e6-d7405bb2fb9d"
}
- The endpoint exposed: https://api.yapily.com/.well-known/jwks.json is used for fetching yapily public keys for verification with jwt.
-
Inside the payload,
exp
(Expiration Time) andiat
(Issue at) can be used to verify the time received is within range to avoid replay attack. -
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
-
Encode a received message body using the algorithm according to
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:
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}