# 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](/products/tol/getting_started/implementing_webhooks/webhooks_categories_types) 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](/api/webhook-subscriptions).

## 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`](/api/webhook-subscriptions/create_webhook)

Example request

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

Example response

```json
{
  "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": "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](/products/tol/getting_started/implementing_webhooks/webhooks_registration)).

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"](/products/tol/getting_started/implementing_webhooks/webhooks_testing)  section.