Overview

The Open Banking API use webhooks for event notifications. The webhooks are push API calls that notify when an event happens.

Webhooks are especially useful for asynchronous events such as, when a file is received, a statement or settlement is received, or if the status of a payment has been updated.

The Open Banking webhooks are built on Azure Event Grid.

Event Subscription

To start receiving events, you must create an event subscription to your Webhook endpoint. The Open Banking API requires you to prove ownership of your Webhook endpoint before it starts delivering events to that endpoint.

Endpoint Validation

For a subscription to be created, your Webhook endpoint code needs to participate in a validation handshake. Event Grid supports two ways of validating your subscription:

• Synchronous handshake: When a subscription is created, a subscription validation event is sent to your endpoint. The event is similar to any other event messages . The data portion of this event message includes a validationCode property. To complete the handshake, your endpoint must return a 200 OK response with the validation code in its body.
• Asynchronous handshake: If you can't return the validation response synchronously, the event message also includes a validationUrl you can use to manually complete the validation handshake. The validationUrl is valid for 5 minutes. If you don't complete the manual validation within 5 minutes, the subscription is deleted, and you will have to create a new subscription.

More information in the EventGrid documentation

Example Subscription Validation Event

[
  {
    "id": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
    "topic": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "subject": "",
    "data": {
      "validationCode": "512d38b6-c7b8-40c8-89fe-f46f9e9622b6",
      "validationUrl": "https://rp-eastus2.eventgrid.azure.net:553/eventsubscriptions/myeventsub/validate?id=0000000000-0000-0000-0000-00000000000000&t=2021-09-01T20:30:54.4538837Z&apiVersion=2018-05-01-preview&token=1A1A1A1A"
    },
    "eventType": "Microsoft.EventGrid.SubscriptionValidationEvent",
    "eventTime": "2021-00-01T22:12:19.4556811Z",
    "metadataVersion": "1",
    "dataVersion": "1"
  }
]

Example Validation Response

Return 200 OK with body:

{
  "validationResponse": "512d38b6-c7b8-40c8-89fe-f46f9e9622b6"
}

Create Event Subscription

You can use the PUT /api/v3/companies/{companyId}/subscriptions/{subscriptionName} to create a new subscription.

A subscription request must contain the following parameters in its body:

The destination object:

Example Request

curl -X PUT "https://bankservice.zdata.no/api/v3/companies/00000000-0000-0000-0000-000000000000/subscriptions/test" 
-H  "accept: text/plain" 
-H  "Content-Type: application/json-patch+json" 
-d "{\"eventTypes\":[\"ZData.Events.Bank.StatementsReceived\"],\"destination\":{\"endpointUrl\":\"https://your_webhook_endpoint.com\",\"maxEventsPerBatch\":10,\"preferredBatchSizeInKilobytes\":64}}"

Retry Policy

If the Open Banking API receives a failure response or is unable to reach a webhook endpoint when posting an event, it will retry delivery up to 30 times. If the maximum number of attempts is exceeded, the event will be dead lettered.

If the Open Banking API experiences delivery failures to a webhook endpoint, it will begin to delay all subsequent event deliveries, including both retries and new events. The backoff-delay may with repeated failures increase to several hours.

Output Batching

By default, the Open Banking API posts event payloads as an array with a single event. You can however configure events to be batched in the subscription configuration. Batching events will improve HTTP performance in high-throughput scenarios.

Batching policy

Batched delivery has two settings:

• Max events per batch : Maximum number of events the Open Banking API will deliver per batch. This number will never be exceeded, however fewer events may be delivered if no other events are available at the time of publish. Must be between 0 and 5,000.
• Preferred batch size in kilobytes : Target ceiling for batch size in kilobytes. Similar to max events, the batch size may be smaller if more events aren't available at the time of publish. It's possible that a batch is larger than the preferred batch size if a single event is larger than the preferred size.

Event Messages

A posted event contains a JSON-Encoded message with a list of events. Each item in the list contains metadata about an event, and a data field with the event payload.

Example Event

[
  {
    "id": "93902694-901e-008f-6f95-7153a806873c",
    "eventTime": "2022-01-01T01:01:01.6018127Z",
    "eventType": "ZData.Events.Bank.StatementsReceived",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "topic": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/zdata-eventgrid-prod-rg/providers/Microsoft.EventGrid/domains/zdata/topics/00000000-0000-0000-0000-000000000000",
    "subject": "/companies/00000000-0000-0000-0000-000000000000/payments",
    "data": {
      "CompanyId": "00000000-0000-0000-0000-000000000000",
      "BatchId": "00000000-0000-0000-0000-000000000000",
      "Links": [
        {
          "Method": "GET",
          "Rel": "payments",
          "Version": "v3",
          "Href": "https://bankservice.zdata.no/api/v3/payments/00000000-0000-0000-0000-000000000000/batches/00000000-0000-0000-0000-000000000000/transactions"
        }
      ]
    }
  }
]

Deadletter Events

If the Open Banking API is unable to deliver an event within a certain time period or if the maximum number of allowed retries is exceeded, the event will be dead-lettered.

Dead letter events can be retrieved from the GET /api/v3/events/deadletters endpoint. The endpoint will return the dead-lettered event, and a failure message that describes the reason the event has been dead-lettered.

Dead-letter specific properties. For a full description of the remaining properties, see Event Messages.

Example response

[
  {
    "id": "93902694-901e-008f-6f95-7153a806873c",
    "eventTime": "2022-01-01T01:01:01.6018127Z",
    "eventType": "ZData.Events.Bank.PaymentStatusUpdated",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "topic": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/zdata-eventgrid-prod-rg/providers/Microsoft.EventGrid/domains/zdata/topics/00000000-0000-0000-0000-000000000000",
    "subject": "/companies/00000000-0000-0000-0000-000000000000/payments",
    "deadLetterReason": "TimeToLiveExceeded",
    "deliveryAttempts": 11,
    "lastDeliveryOutcome": "GenericError",
    "lastHttpStatusCode": 500,
    "publishTime": "2022-01-01T01:01:02.6018127Z",
    "lastDeliveryAttemptTime": "2022-03-01T01:01:01.6018127Z",
    "data": {
      "CompanyId": "00000000-0000-0000-0000-000000000000",
      "BatchId": "00000000-0000-0000-0000-000000000000",
      "Links": [
        {
          "Method": "GET",
          "Rel": "payments",
          "Version": "v3",
          "Href": "https://bankservice.zdata.no/api/v3/payments/00000000-0000-0000-0000-000000000000/batches/00000000-0000-0000-0000-000000000000/transactions"
        }
      ]
    }
  }
]