Registering a webhook

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

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

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.

Specify which event categories you want to receive webhooks for.

For a complete list of available event categories and their types, see event categories and types.

Use the type field to set which events you want to receive.

Choose one of the following:

1. Receive all webhook events: Set the type field to ALL.
2. Exclude specific webhook events: Set the type field to ALL and populate the exclude_type field with the event types you want to exclude.
3. Subscribe to specific webhook events: Set the type field to include only the event types you want to receive.

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 send a webhook payload bigger than the configured maximum.

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

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

See the webhook subscriptions specification.

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 are 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
  }
}

Once you've completed the step above, you're ready to register a new webhook.

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