Registration of webbhooks

This section guides you through the process of registering a new webhook in the Upvest Investment API.

Gathering information

To create a webhook, provide the following information to the Investment API:

1. URL

A URL under your control for receiving incoming webhook payloads sent by the Investment API.

• The scheme of the URL is restricted to be the HTTPS protocol only.

• The 'host' part of the URL is restricted to DNS names only, no IP addresses.

• The called URL must not respond with HTTP redirects (3xx).

• The server that processes the URL should support TLS version 1.2 or higher.

2. Event categories

A list of event categories you want to receive webhooks for.

Under the following link you will get the complete list of all available event categories including the corresponding types.

3. Maximums

To reduce the load of high event volumes, events are batched either by time or size. You can specify the maximum payload size and/or the maximum delay between payloads that you are willing to accept.

• The delay must be a string in the format numberunit*, for example 1s, 5s, 1m.

• The smallest possible delay is 1s.

• The Investment API supports the units s for seconds and m for minutes.

• The package size is in bytes. For example 10240 is for 10 KiB. If you specify a small size here, and a single event payload exceeds it, then we will send a webhook payload bigger than the configured maximum.

4. Title

You can add a title to a webhook to help distinguish it from other webhooks.

Creating webhook subscriptions

In order to register a webhook, you'll need to take the information you gathered, and format it as an HTTP POST request to the /webhooks endpoint of the Upvest Investment API.

You can find the Open API specification for creating, reading, updating and deleting webhook subscriptions here.

Example registration of a webhook

In this example, we register a webhook with the following details:

• The title is User Webhook.
• The URL is https://tenant.tld/webhooks/users.
• We are only interested in events in the USER category.
• Payload batches will be sent every 5 seconds or less.
• The payload size will not be greater than 10240 bytes.

We send a POST /webhooks

{
  "title": "User webhook",
  "url": "https://tenant.tld/webhooks/users",
  "type": [
    "USER"
  ],
  "config": {
    "delay": "5s",
    "max_package_size": 10240
  }
}

Now you're ready to register webhooks. If you've completed the step above, you should be able to register a new webhook.

Next Steps

We suggest you continue by returning to the "Implementing Webhooks" tutorial and reading the "Test Webhooks" section.