Notifications

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:

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

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:

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

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 and Virtual Accounts. See the following pages for the available event types:

• Payments
• Virtual Accounts

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.