Wealth Wizards

How-to Guides

Guides on common tasks like authenticating and accepting webhooks.

Common tasks

Enabling user data pre-population

How to pre-populate user journey's to create a seamless user experience.

The Wealth Wizards platform supports seamless integration where user data can be sent in real time to our servers. We then use this information to pre-populate the user's journey throughout our apps.

This guide will walk you through the steps necessary to enable pre-population.

For this guide, we'll be relying upon the SSO integration we set up in the previous guide. We will also be making use of the login event that is accessible to all of Wealth Wizards' customers -- you can find a full list of events we make accessible here.

Pre-population of user data reduces friction and increases user engagement. Below are a few examples of this throughout our app:

  • A user's Target Retirement Age
  • A user's Pension Fund Value
  • A user's pension contributions (either as a monthly amount, or as a salary, employer, and employee contributions breakdown)
  • Postcode to predict whether a user “lives in London” (for PGT lifestyle costs)
  • Postcode to predict whether a user “lives in Scotland” for income tax projections
  • The age field within the Financial Health Check

Financial Health Check Pre-Population

Integration Overview

For this integration there four steps necessary to enable pre-population:

  1. Subscribing to Login Events (registering webhook notification)
  2. Responding to the Login Event Webhooks
    1. Correlating user records
    2. Sending Pension Data to our servers

This will then result in a flow that works like:

  1. User Authenticates with SSO
  2. Wealth Wizards notifies you that a user has signed in
  3. You correlate the user that has logged in and find their record
  4. You send the user's pension data back to us via the Client Data API

sequence diagram of end-to-end flow

Getting started - Subscribing to Login Events

The first step in this process is for you to be notified whenever one of your users logs into our product.

Using the Wealth Wizards Webhook functionality we can subscribe to the user.login event which gets emitted every time one of your users logs into our products.

You can find a full list of events which we make accessible here.

To subscribe to our events it is as simple as sending an email to your Wealth Wizards account director with the following details:

  • OAuth Client Credentials:

    • authorization_endpoint: The URL used to interact with the resource owner and get the authorization to access the protected resource.
    • client_id: The client ID we will use to redeem a valid token.
    • client_secret: The client secret we will use to redeem a valid token.
    • http_method: The http method we will use against the authorization endpoint.
    • scope: A space-delimited list of permissions that the application requires.
  • Webhook Destination:

    • destination_endpoint: The URL we will send the event to.
    • http_method: The http method we should use when sending the event.

Configuration Portal Coming Soon

A fully automated, self-serve portal to configure webhook subscriptions is currently in developement.

Correlating User Details / Processing the Login Event

Once we've processed the webhook connection, you will begin to see requests hitting the endpoint you registered with us.

The body of the request will contain the following information:

  "id": "f2448dbd-8b17-290a-a8da-e276d01fd937",
  "type": "user.login",
  "detail": {
    "email": "joe.blogs@mail.com",
    "sub": "a91e3725-a8c5-43b1-8466-3bbf2d7458aa",
    "identities": [
        "userId": "da2nR-25MSWVOK0TOqVMjh-GJ1z_U0pWuqE2xV64hD4",
        "providerName": "tenant-stage-oidc-provider",
        "providerType": "OIDC",
        "issuer": null,
        "primary": true,
        "dateCreated": "2022-03-08T13:24:53.499Z"
  "createdAt": "2022-10-07T09:57:29Z"

You will notice that there are two unique Identifiers within the login event:

  • detail.identities.userId: Your identity server's unique ID for the logged in user.
  • detail.sub: The Wealth Wizards' unique ID for the logged in user.

These two Unique Identifiers allow you to correlate the Wealth Wizards' record with the user's record that you have within your system.

Saving the Wealth Wizards ID

When interacting with our APIs to modify/update a user record, we will require the Wealth Wizards' ID to be provided as this is the ID that our servers recognise.

That's why we recommend saving the Wealth Wizards' ID from this event along side your user's record. This will allow you to call our APIs at any time -- not just when responding to login events :)

Updating the User Record

Now that you have the Wealth Wizards' User ID accessible, you can start sending pension data to us via the Client Data API -- enabling us to pre-populate and personalise the user's experience.

To do this we are going to use the Client Data API's /pensions route. The API reference for it is here and lists all of the required fields needed for a successful request to be made.

The route is protected via OAuth Client Credential Authorisation, the details along with the client_secret will have been sent securely after becoming a customer of ours and can also be requested at any time.

An example body for the POST request you will make to the /pensions/v1/:userId route:

  "client": {
    "forename": "John",
    "surname": "Smith",
    "dateOfBirth": "1970-10-23",
    "sex": "male",
    "salary": 30005.75,
    "retirementDate": "2035-10-23",
    "postcode": "CV34 6RT",
    "pensions": [
        "providerName": "Wealth Wizards Pensions",
        "planName": "WW Pension Plan",
        "planNumber": "WW0123456789",
        "schemeNumber": "WW/0123",
        "productType": "DB-123",
        "retirementDate": "2035-10-23",
        "contributions": {
            "frequency": "monthly",
            "employeePercentage": 4,
            "employerPercentage": 8,
            "employeeAmount": 1200.23,
            "employerAmount": 2400.46,
            "totalAmount": 3600.69
        "fundValue": 100000.54

Next Steps

This guide has walked you through the end-to-end process of getting pre-population enabled between Wealth Wizards and your users; creating a seamless experience between services, but there's no reason to stop here.

Our platform supports a whole host of other webhook notifications that you can subscribe to which will further enhance the integration with our products.

If you need assistance, please reach out to Wealth Wizards through the standard technical support channels and we'll be more than happy to help.