Webhooks enable you to make the most of the Investment API by enabling asynchronous interaction with your system whenever a state change occurs across all applicable business domains.

This document outlines what webhooks are and how they can be used.


A webhook (sometimes referred to as a 'callback operation') is a push message function to which you can subscribe. Within our Investment API, webhooks are broadly used to actively communicate state changes to our clients (i.e. you). The client in this use case would be defined as a 'listener' who provides a URL through which a potential push message can later be received.

How webhooks work

The Upvest architecture was designed as an asynchronous, event-driven system. Events in this context are records of something that has happened, a change of state. Events are immutable and ordered in sequence in which they occur. In general, an event-driven architecture refers to a system of loosely coupled microservices that exchange information with each other through the creation and consumption of events. This architecture approach is commonly considered as good systems design, because:

  • The event-driven architecture prevents a client from having to constantly polling to determine state changes.
  • It allows for true decoupling of producers and consumers as microservices.
  • A single source of truth with a log of immutable events.
  • Eventing systems tend to be more resilient as they are only loosely coupled.

All information that is exposed through webhooks is also accessible through our HTTP API, however, much more powerful and convenient use cases are facilitated by leveraging webhooks.

Use cases

The range of webhook use cases within Upvest's current product functionalities is wide. Mainly because the concept of a 'state-change' is ubiquitous in financial architecture.

The application of this concept runs through all of Upvest’s business domains. Below are some of the many possible use cases for webhooks.

  • Users: status changes related to a user’s account status, the status of a user’s onboarding due diligence checks.
  • Initial deposit: tracking whether funds have been successfully deposited so that a buy order can be placed.
  • Payments: identify the status of an outgoing payment processing.
  • Orders: status changes during the order processing cycle, from initial submission to tracking cancellations to full processing.
  • Reporting: status changes during report generation - allows a file to be retrieved as it is created.

In our tutorial 'Implementing webhooks', we describe in detail how to implement webhooks.

Was this page helpful?