Webhook Registration

This sub-task guides you through the process of registering a new Webhook in the Upvest Investment API.

 1    Gather Information

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

1.2   Event Categories

A list of event categories you want to receive Webhooks for. The list of currently supported categories includes USER, ORDER and USER_CHECK, but this list will expand rapidly beyond the publication of this guide.

Note: If you need all of the events, use the ALL category.

1.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 {number}{unit}, 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.

1.4   Title

You can add a title to a Webhook to help distinguish it from other Webhooks.

 2    Creating Webhooks

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 Webhooks 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 request, including the following body:

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

We receive the following response from the Upvest Investment API:

{
  "id": "a8eb3540-5a84-40f9-b2bb-7f99f282fc5a",
  "created_at": "2021-07-21T14:10:00.00Z",
  "updated_at": "2021-07-21T14:10:00.00Z",
  "title": "User webhook",
  "url": "https://tenant.tld/webhooks/users",
  "type": [
    "USER"
  ],
  "enabled": false,
  "config": {
    "delay": "5s",
    "max_package_size": 10240
  }
}

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

 ✔    You're ready to register Webhooks!

Congratulations! 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 your Webhook" section.