Webhooks
A webhook is an HTTPS endpoint hosted in your backend that will handle requests from the Upvest Investment API. In this way you can trigger actions in your own code based on events happening within Upvest's backend.
Many webhooks provide status updates on business processes that are initiated by API calls within the Investment API. The delivery of status via webhooks is not intended to act as a substitute for confirmation of the success or failure of that initial API call.
You should always inspect the returned HTTP status of your API calls to determine whether it was successful or not. Should that call fail, it can be repeated, with an idempotency key.
In order for these HTTP requests to come form Upvest to you, it is necessary to inform the Investment API of the endpoint it should call, and in response to which kind of events. The Investment API provides endpoints for the management of this information. You can create, read, update and delete (CRUD) Webhooks and to test-trigger them to help you integrate with the Investment API.
In this tutorial you will learn how to implement webhooks so that you can receive events from the Upvest Investment API.
Prerequisites
Please make sure you meet the following conditions before attempting this tutorial.
Understand the concept of a webhook
If you're not already familiar with the concept of a "Webhook", please take a moment to read our "API Concepts: Webhooks" documentation.
Know how to implement an HTTP endpoint
This tutorial is designed for backend engineers with experience implementing HTTP endpoints for API calls. If you do not have this experience seek the help of someone in your organisation who does before continuing.
Add Upvest IP addresses to allow list
Upvest will send events to your Webhook endpoint from specific IP addresses. You must add these IP addresses to your allow list to ensure that you can receive these events. Please see the IP Addresses documentation for more information.
Implementation steps
The following steps will lead you through our recommendations for the implementation of a webhook handler endpoint, and the use of the Upvest Investment API to create and manage webhooks.
Webhook implementation is a three step process:
- Implement your webhook handler
Read this guide to understand the requirements for a webhook handler endpoint within your backend.
-> Implement a Webhook Handler
- Register your webhook
In order for your webhook to be utilised by the Upvest Investment API, we must be informed of its existence. This registration is performed within the API itself.
Read this guide to find out how to register and manage your webhook.
- Test your webhook
Once you've implemented and registered your webhook, it's time to test it. This sub-task explains how you can trigger test requests via the Upvest Investment API.
Further readings
As well as registering new webhooks, the Upvest Investment API offers a number of other functions for managing your registered webhooks.
Discover the management functions here.
We also recommend that you take a look at the best practices, where we share tips for webhook implementation.