Notifications

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

Introduction

Notifications proactively, and in real time, alert you to relevant asynchronous events or processes that have occurred on your application. This avoids you needing to make continuous requests to the API.

Notifications are delivered via webhooks.

Accepting webhooks

Create a webhook endpoint

Webhook notifications are delivered to your application using HTTPS. You need to create an endpoint (URL) to receive them.

You can receive events on the same or different endpoints.

Receive 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. The object includes identification of the eventType and an eventPayload object with a payload specific to the event type.

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 The unique ID of the notification No
eventType The type of event you're being notified of No
applicationId The unique ID of the associated client application No
institutionId The institution related to the event you're being notified of Yes
eventPayload Details the event you're being notified of

The payload differs according to the eventType		 No
objectId The unique ID of the resource that relates to the notification (e.g. the paymentId of the payment for a payment.status notification) No
consentToken The consent Yapily used to retrieve an update from the institution Yes
created The time the notification was created No
url The URL where the notification is delivered to (provided as part of the event subscription) No
notificationStatus Delivery status of the notification (e.g. DELIVERED) No

Respond to the notification

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

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

Verify 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 signed JWT.

JWT payload:

Copy
Copied
{
  "digest": "C1073039BD591D97D5991CFF6583D091AABF2005C99EC5523BE3C37EA8F6381A",
  "enc": "SHA256",
  "exp": 1647970592,
  "iat": 1647970291,
  "jti": "553a3ed6-914a-4062-b7e6-d7405bb2fb9d"
}

You can use the endpoint https://api.yapily.com/.well-known/jwks.json to fetch Yapily public keys for verification with JWT.

Inside the payload, you can use exp (expiration time) and iat (issue at) to verify that the time received is within range to avoid replay attack.

You can use digest to verify that 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 to see if they are the same

Managing notification subscriptions

Subscribe to notifications

Use POST /notifications/event-subscriptions to subscribe to an event type.

In the request body, include the event you want to subscribe to in the eventTypeId field and the URL where you want to receive the notification webhook in the url field.

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

Notifications are currently offered for Payments. See the following page for the available event types:

Check subscribed notifications

Use GET /notifications/event-subscriptions/{eventTypeId} to verify if you are currently subscribed to a specific event type.

Use GET /notifications/event-subscriptions to retrieve the list of events you are currently subscribed to.

Unsubscribe from an event type

Use DELETE /notifications/event-subscriptions/{eventTypeId} to unsubscribe from an event type.