Skip to content
Documentation/
/
/
Registering a Webhook

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 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.

If you need all the events, use the ALL category.

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.
  • The smallest possible delay is 1s. The maximum delay is 30s. Usually, a delay of 1s is sufficient.
  • 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 2 seconds or less.
  • The payload size will not be greater than 51200 bytes.

We send a POST /webhooks

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

All webhooks are created with the status disabled, which means that no data is sent until you set enabled: true by sending a PATCH request, see (update a webhook).

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.