# Registering a webhook

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

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](/products/tol/getting_started/implementing_webhooks/webhooks_categories_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.


The `exclude_type` parameter only takes effect when `type` is set to `ALL`. It has no effect when `type` contains a specific list of event 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`.
* 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.


### 4. Title

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

## Creating webhook subscriptions

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](/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 are 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_managing#updating-webhooks)).

Once you've completed the step above, you're ready 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.