Guides

Webhooks

Webhooks

Overview

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

Why webhooks?

Webhooks provide a push-based model to proactively notify partners when relevant events occur. D•One uses webhooks to notify partners when Open Banking data has been processed and ready for consumption.

If a partner does not wish to use webhooks they can use a pull-based approach by polling the Accounts endpoint to check whether a user’s Open Banking (OB) data is available. Further details on polling can be found here.

NOTE - Webhooks are available for new connections and refreshes on users sourced via direct connections only.

Available events

The following events are currently available for subscription.

v1.account_transactions.user_initiated.succeeded

This event is triggered after a user has connected their bank account, Open Banking data has been fetched, processed and ready for consumption. The event is emitted per account, with individual webhooks fired once for each account.

Partners can subscribe to this event to be notified as soon as the Open Banking data for the account is ready to be consumed.

v1.account_transactions.scheduled_refresh.succeeded

This event is triggered when D•One completes a scheduled refresh of Open Banking data for a connected account. It is emitted per account, with individual webhooks fired once the Open Banking data has been refreshed.

Partners can subscribe to this event to be notified as soon as the Open Banking data for the account is refreshed and ready to be consumed.

Savings Goal account behaviour

Although Savings Goal account types have no transaction data, the webhook will still be emitted and included in normal webhook processing.

For these account types, D•One updates only the account data.

After receiving a webhook for a Savings Goal account, partners can decide how to handle it based on their own use case. For example, they could refresh the account balance or take no action.

How it works

D•One exposes endpoints that allow partners to manage their webhook subscriptions.

High-level flow

Webhook high level flow

Steps

  1. Webhook secret sharing

    D•One 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.

  2. 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 D•One.

  3. Event delivery

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

  4. 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.
    • D•One 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.

  5. Data retrieval

    After receiving the webhook event, partners can fetch the user's Open Banking data from D•One using the relevant API endpoints.

Retries and failure handling

If D•One 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 D•One 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

  • D•One 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 D•One.

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

Verification process

To verify an incoming webhook request, partners must:

  1. Read the raw request body exactly as received (without modification).
  2. Generate an HMAC SHA-256 hash of the payload using the shared webhook secret.
  3. Prefix the generated hash with sha256=.
  4. Compare the computed value with the signature provided in the X-Webhook-Signature header.
  5. 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

D•One currently supports manual rotation of webhook secrets. Partners can rotate secrets by coordinating with the D•One 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, D•One 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, D•One will:

  1. Construct a sample webhook payload for the selected event type.
  2. Sign the payload using the shared webhook secret.
  3. Send the webhook request to the specified target URL.
  4. 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

D•One 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 D•One 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 D•One 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 D•One 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.

Updated 21 days ago