Webhooks

Overview

Webhooks allow DataOne to notify partners in real time when Open Banking data is ready for consumption.

Why webhooks?

At present, partners are advised to poll the Accounts endpoint to determine when a user’s Open Banking (OB) data is available. This approach does not scale well and can result in unnecessary load and delays.

Webhooks remove the need for polling by proactively notifying partners when relevant events occur.

NOTE - Webhooks are available with users sourced via direct connections only.

Available events

The following events are currently available for subscription. Additional events will be introduced in the future.

`v1.account_transactions.succeeded`

This event is triggered after a user has connected their bank accounts. It is emitted per account, with individual webhooks fired once each account's transaction data has been fetched and is ready for consumption.

Partners can subscribe to this event to be notified as soon as each account's transaction data is ready.

When creating a subscription, partners must specify the transaction categorisation version they wish to receive, ensuring notifications are sent only for the relevant data set.

How it works

DataOne exposes endpoints that allow partners to manage their webhook subscriptions.

High-level flow

Steps

Webhook secret sharing

DataOne will share a secret with the partner. This secret is used to sign webhook payloads.

Partners must use this secret to verify the webhook signature and ensure the request is authentic.
Create a webhook subscription

Partners create a webhook subscription using the POST subscription endpoint.

The request must include a target URL that is capable of receiving webhook events from DataOne.
Event delivery

Once the applicant has connected their bank accounts via Open Banking and the data is available in DataOne, a webhook event will be sent to the partner’s configured target URL.
Webhook verification and response

Partners must:
- Verify the webhook signature using the shared secret.
- Respond with a 2xx HTTP status code to confirm successful receipt and processing of the event.
- DataOne applies a 5-second timeout to webhook deliveries. If no response is received within this window, the delivery is treated as failed and will be retried.
Data retrieval

After receiving the webhook event, partners can fetch the transaction data from DataOne using the relevant API endpoint.

Retries and failure handling

If DataOne receives a non-2xx response, the webhook delivery will be retried. The retry interval is measured from the most recent failed attempt, not the initial attempt.

Maximum retries: 3
Retry intervals:
- 30 seconds
- 1 minute
- 5 minutes

If all retry attempts fail, the event will be marked as undelivered.

Signature verification

All webhook requests sent by DataOne are signed to allow partners to verify their authenticity and integrity.

Each request includes a signature generated using the shared secret. Partners are required to verify this signature before processing the webhook event.

If signature verification fails, the webhook request must be rejected.

Signature generation

DataOne generates a signature by computing an HMAC over the raw request payload.
The HMAC is created using the SHA-256 hashing algorithm and the shared webhook secret.
The resulting signature is included in the request headers.

Request headers

Webhook requests are sent to the partner’s configured target URL with the following headers:

POST /<partner-target-url>
X-Webhook-Id: <UUID>
X-Webhook-Timestamp: <timestamp>
X-Webhook-Signature: sha256=<signature>

X-Webhook-Id

A unique identifier for the webhook event delivery.
X-Webhook-Timestamp

The time at which the webhook was generated.
X-Webhook-Signature

The HMAC signature generated by DataOne.

The value is prefixed with the hashing algorithm used (sha256).

Verification process

To verify an incoming webhook request, partners must:

Read the raw request body exactly as received (without modification).
Generate an HMAC SHA-256 hash of the payload using the shared webhook secret.
Prefix the generated hash with sha256=.
Compare the computed value with the signature provided in the X-Webhook-Signature header.
Process the webhook only if the signatures match.

If the signatures do not match, return a non-2xx HTTP response and do not process the event.

Key and secret rotation

DataOne currently supports manual rotation of webhook secrets. Partners can rotate secrets by coordinating with the DataOne team.

An automated secret rotation mechanism will be introduced in a future release.

Testing your webhook endpoint

To verify that your webhook endpoint is configured correctly, DataOne provides a test endpoint that can be used to send sample webhook events to your target URL.

Purpose

The test endpoint allows partners to:

Validate that their target URL is reachable
Confirm that webhook payloads are received successfully
Verify signature validation and response handling before going live

How it works

Using the test endpoint, partners can specify:

The webhook event type they wish to test
The target URL that should receive the webhook

Once invoked, DataOne will:

Construct a sample webhook payload for the selected event type.
Sign the payload using the shared webhook secret.
Send the webhook request to the specified target URL.
Evaluate the HTTP response returned by the endpoint.

Response behaviour

The test endpoint will return a success or failure response indicating whether the webhook delivery was successful.

Partners should also review their own application logs to confirm that:

The webhook request was received
The payload was processed as expected
The endpoint returned the appropriate HTTP response

Managing webhook subscriptions

DataOne provides a set of RESTful endpoints that allow partners to manage their webhook subscriptions programmatically.

Using these endpoints, partners can:

All webhook management endpoints are accessed using the same API key as the rest of the DataOne API.

These endpoints enable partners to control which events they receive, where webhook events are delivered, and how subscriptions are maintained over time.

Full details, including request and response schemas, are available in the API documentation.

Partner responsibilities

Partners are responsible for ensuring the following when integrating with DataOne webhooks:

Your webhook endpoint must respond with an HTTP 2xx status code within 5 seconds.
Your webhook endpoint must be accessible over HTTPS and support TLS 1.2 or higher.
Your system must be able to handle duplicate webhook events.
Your system must be resilient to out-of-order event delivery.
Your implementation must verify the webhook signature X-Webhook-Signature to confirm authenticity.
Your endpoint must return a non-2xx response only when a retry is required.

Integration best practices

1. Reliability & idempotency

Webhook events are delivered on an at-least-once basis, meaning duplicate events may occur.
Webhook handlers should be idempotent, for example by using event IDs to detect and de-duplicate repeated events.

2. Performance & responsiveness

Respond quickly with a 2XX HTTP status. Perform heavy processing asynchronously (e.g. enqueue the event and process it later).

3. Security

Always verify webhook authenticity (HMAC signatures).
Do not rely solely on IP allow-listing, as IPs may change.

4. Schema & evolution

Validate incoming payloads against the expected schema.
Ignore unknown fields to ensure forward compatibility.
Handle missing or optional fields gracefully.

5. Error handling

Return a non-2xx status code only when you want DataOne to retry delivery.
Clearly distinguish between retry-able and permanent failures in your logs.

6. Debuggability

Log request headers and payloads for troubleshooting.
Ensure sensitive data is masked or scrubbed before logging.