Event Polling

The Event Polling API facilitates storing and retrieving event notifications according to the above specifications without altering the information in the event information JSON. Event Polling API is secured with basic authentication (admin username and password) and accept base64 encoded JSON. The Event Polling API follows the IETF Security Event Token (SET) and the Poll-Based Security Event Token (SET) Delivery Using HTTP specifications to serve general-purpose event notification creation and polling.

This endpoint allows applications to poll for, acknowledge, and receive event notifications. You can use this endpoint when the API consumer applications communicate their polling parameters and event notification acknowledgements. Using this endpoint the banks can respond accordingly; sending event notifications as indicated by the application's polling parameters.

You can customize the Event Polling Flow according to your requirements. For more information, see Customizing Event Notification.

Based on the request payloads, the Event Polling(POST /events) endpoint performs the following:

  • Poll for events
  • Acknowledge the received events
  • Acknowledge error notifications
  • Poll for new events and acknowledge the received events at once

A sample Event Polling request is as follows:

 curl --location --request POST 'https://localhost:9446/api/openbanking/event-notifications/events' \
 --header 'Authorization: Basic YWRtaW5Ad3NvMi5jb206d3NvMjEyMw==' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data-urlencode 'request=eyAKICJyZXR1cm5JbW1lZGlhdGVseSI6IHRydWUsCiAibWF4RXZlbnRzIjogMCAKIH0='

Note

The Event Polling(/events) endpoint supports the request payloads mentioned in the Poll-Based Security Event Token (SET) Delivery Using HTTP specification.

Tip

The API consumer applications can send two polling parameters to indicate the polling behaviours:

  • returnImmediately: Indicates whether a bank should return a response immediately or provide a long poll. WSO2 Open Banking currently does not support Long Polling. Therefore, the value of returnImmediately is always true.
  • maxEvents: The maximum number of events to be returned. A value of 0 indicates the bank should not return events even if available. The upper bound value of the parameter depends on the size of the payload and the connection. If the maxEvents value is not defined in the payload, the value will be set according to the number_of_sets_to_return configuration in <IS_HOME>/repository/conf/deployment.toml.

Given below are sample Event Polling request payloads (in the decoded format) and their responses:

  • When requesting a response immediately, only to make sure there are events available:

    {
   "setErrs":{
      "65ac7453-13b0-4d2f-9946-dff6e6089a4f":{
         "err":"authentication_failed",
         "description":"The SET could not be authenticated"
      }
   },
   "returnImmediately":true,
   "maxEvents":0
}
    {
    "moreAvailable":true,
    "sets":{ }
}

  • When confirming that there are events. If there are 5 events available with the bank and the application wants to receive only 3 events:

    {
   "returnImmediately":true,
   "maxEvents":3
}
    {
   "moreAvailable":true,
   "sets":{
      "a4a07198-5fec-448b-b7d0-c61e5fe122dc":"eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJHZllacWhidFZYWjBVSldTR2JRbDZPd294b29hIiwiYXVkIjoiR2ZZWnFoYnRWWFowVUpXU0diUWw2T3dveG9vYSIsImlzcyI6Ind3dy5vcGVuYmFuay5jb20iLCJ0eG4iOiJiOWNlY2RmYi0wYWQwLTRiZmYtOTk2YS0zNjZkNjk0MWUyMjUiLCJ0b2UiOjE2NDY2NTYzODQwMDAsImlhdCI6MTY0NjcxMDA4MywianRpIjoiYTRhMDcxOTgtNWZlYy00NDhiLWI3ZDAtYzYxZTVmZTEyMmRjIiwiZXZlbnRzIjp7InVybl91a19vcmdfb3BlbmJhbmtpbmdfZXZlbnRzX3Jlc291cmNlLXVwZGF0ZSI6eyJrZXkyIjoidmFsdWUiLCJyZXNvdXJjZUlEIjoidmZqc2tlbmZrc2RudmZra2ZkZmQnIiwia2V5MyI6InZhbHVlIn0sInVybl91a19vcmdfb3BlbmJhbmtpbmdfZXZlbnRzX2NvbnNlbnQtYXV0aG9yaXphdGlvbi1yZXZva2VkIjp7ImtleTIiOiJ2YWx1ZSIsInJlc291cmNlSUQiOiJ2Zmpza2VuZmtzZG52ZmtrZmRmZCciLCJrZXkzIjoidmFsdWUifX19.ZGuLQEELC3RaQaBVDeK0eConHjWf5aw7QH60jHMkKwhFILNHs6Rn9sYIb-EORO1yGFrrEXaXOUAZLY23gADqGVCbNr3rGr-ye78hB0XAkNgY5Ur5ois43so6H1yvOOL1ddmXDwSOtOwxQM5UFNjNwSiutI1LDvTZ-T0_v9EsGsEeXLFd56sHhS9VAuKFhLHm9N8vsxc4dt6yx2e5KGIP7Mpx3PQZiPRWLObiPx5SEhDGSonskQurcXynBisOvjuvgI5BBAlSKOsOwWX1pC4PHTppHOv20xBu2b2lcFdl8TH1fKm_Btmd7cORTqj4TuXnQMKhKtOjyKoU81fCq3BySw",
      "44c27e45-063d-4ba6-82f1-5073d641fe25":"eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJHZllacWhidFZYWjBVSldTR2JRbDZPd294b29hIiwiYXVkIjoiR2ZZWnFoYnRWWFowVUpXU0diUWw2T3dveG9vYSIsImlzcyI6Ind3dy5vcGVuYmFuay5jb20iLCJ0eG4iOiIwNzMzMDU2Ny1mZDAyLTQ5ODctYWUxMi1jMmZlYTdmZDY2OTEiLCJ0b2UiOjE2NDY2NTYzOTAwMDAsImlhdCI6MTY0NjcxMDA4MywianRpIjoiNDRjMjdlNDUtMDYzZC00YmE2LTgyZjEtNTA3M2Q2NDFmZTI1IiwiZXZlbnRzIjp7InVybl91a19vcmdfb3BlbmJhbmtpbmdfZXZlbnRzX3Jlc291cmNlLXVwZGF0ZSI6eyJrZXkyIjoidmFsdWUiLCJyZXNvdXJjZUlEIjoidmZqc2tlbmZrc2RudmZra2ZkZmQnIiwia2V5MyI6InZhbHVlIn0sInVybl91a19vcmdfb3BlbmJhbmtpbmdfZXZlbnRzX2NvbnNlbnQtYXV0aG9yaXphdGlvbi1yZXZva2VkIjp7ImtleTIiOiJ2YWx1ZSIsInJlc291cmNlSUQiOiJ2Zmpza2VuZmtzZG52ZmtrZmRmZCciLCJrZXkzIjoidmFsdWUifX19.hBczP5eyLl1bDyhPiuFBCUYM63C3mEq8Sx9Emkgdnz15K5pcEjYdLqDYjId8Pm2ev4-wxrXq4q1832dytDQriFTwR6rW5pYdeVWeRQSvVZ6YB9xbo1fRpqSTxgWuKKHBtiPRXff7Vcp6RGViSq7znCBLGjo1ban9-t2fR6CTlY__iMK-hjJmBQhHnPJzw0qUfAckqwkEEPUNeykQfhFS_07N5vFVw9ILuXlrJaxtsyS6mwEPNJK4cChUwuoKdN9HqmpvUzFBS3xrRXbwB5ASM6pZUCmmOncXUkYu9muCbtNNiHrev3gCjOvw9PDwlHxMscsQz4kZImOd48zGsYd-jg",
      "4b1dfb62-a08d-4704-9944-f05cc4cab43b":"eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJHZllacWhidFZYWjBVSldTR2JRbDZPd294b29hIiwiYXVkIjoiR2ZZWnFoYnRWWFowVUpXU0diUWw2T3dveG9vYSIsImlzcyI6Ind3dy5vcGVuYmFuay5jb20iLCJ0eG4iOiI2YWMxYjdiYi03NGM1LTQ2YmUtYWUwMi04YjgzZWVkNGQ2Y2UiLCJ0b2UiOjE2NDY2NTYzOTUwMDAsImlhdCI6MTY0NjcxMDA4MywianRpIjoiNGIxZGZiNjItYTA4ZC00NzA0LTk5NDQtZjA1Y2M0Y2FiNDNiIiwiZXZlbnRzIjp7InVybl91a19vcmdfb3BlbmJhbmtpbmdfZXZlbnRzX3Jlc291cmNlLXVwZGF0ZSI6eyJrZXkyIjoidmFsdWUiLCJyZXNvdXJjZUlEIjoidmZqc2tlbmZrc2RudmZra2ZkZmQnIiwia2V5MyI6InZhbHVlIn0sInVybl91a19vcmdfb3BlbmJhbmtpbmdfZXZlbnRzX2NvbnNlbnQtYXV0aG9yaXphdGlvbi1yZXZva2VkIjp7ImtleTIiOiJ2YWx1ZSIsInJlc291cmNlSUQiOiJ2Zmpza2VuZmtzZG52ZmtrZmRmZCciLCJrZXkzIjoidmFsdWUifX19.WuCofwrejo7DJshARa2IRdZzXIoXqeX9EF8le3W2zWC1mvaFTA80iqa4PrUm416IkzogMd_yQHlioZ7Wkx9A1JOsrKetut3IVGTM7SgZoVmW1GMYP5JFV8XO8k5TyStNTrXSYTb7yADs17oe7Bn6oETStmGBUEJh4hul31ABF_P_hTwfPp9udAI_jHzpQBwhKkDE1--6ygRHjURCcj23WJDPKv6ZtHJpNxQm23x0L5Mr_tsNs8wRGQqEraNzuP964_fbtXXnF6EDGg6W0cRHSxxbSE3wx7uhYVdweWYYPrbGXXs9uxbeFoJryg4ydThzTGq9wnxvjxc3Kr_7EZW9Vg",
   }
}

  • To acknowledge the received events (both positive and negative acknowledgments) while accepting more events. If there are more events available with the bank. The application continues requesting events until there are no more events.

    {
   "ack":[
      "1256db1c-8fda-4457-a755-bb5113dba717"
   ],
   "setErrs":{
      "65ac7453-13b0-4d2f-9946-dff6e6089a4f":{
         "err":"authentication_failed",
         "description":"The SET could not be authenticated"
      }
   },
   "returnImmediately":true
}
Top