# Webhook over mTLS for clients

## Introduction

This page explains how webhook delivery over mTLS works, why you should use it with HTTP signatures, and how to manage certificate setup and rotation for sandbox and live environments.

## mTLS overview

Mutual Transport Layer Security (mutual TLS, or mTLS) is a security protocol that provides **two-way authentication** between Upvest and your webhook endpoint. Unlike standard HTTPS, mTLS requires both sides to present valid certificates during the TLS handshake.

## Benefits of using mTLS

When you enable mTLS for webhook delivery, you add:

* Strong endpoint authentication
* Connection-level security


mTLS is an additional security layer on top of HTTP signature verification.

Use both mechanisms together for defence in depth: mTLS authenticates the **connection**, while HTTP signatures authenticate the **payload content**.

## Prerequisites

Before Upvest can deliver webhooks over mTLS, configure your webhook endpoint to:

* **Run HTTPS with TLS 1.2 or later**
* **Request a client certificate** during the TLS handshake
* **Validate the client certificate** against your trust store
* **Reject connections** that do not present a valid certificate


mTLS is configured per client. After mTLS is enabled, all webhook deliveries for that client use mTLS.

## Certificate requirements

To enable mTLS, provide Upvest with the following files in PEM format:

* **Private key**
* **Client certificate**


Your certificate must meet these requirements:

* **Key algorithm:** RSA, 4096-bit
* **Signature algorithm:** SHA-256


Send both files using your agreed secure transfer mechanism, for example password-protected encrypted bundles. Label each bundle clearly by environment. Upvest reviews and stores the files securely before enabling integration.

## Initial key configuration

Complete initial setup with the following steps:

Generate certificate bundle
Generate a certificate bundle that contains both the private key and client certificate in PEM format.

Prepare environment-specific bundles
Provide separate bundles for sandbox and live, and label each bundle clearly.

Submit bundles securely
Send the bundles to Upvest through your agreed secure channel.

Upvest review and confirmation
Upvest reviews and securely stores the bundles, then confirms when integration can begin.

Integration and validation
Upvest starts integration testing against your endpoint and confirms successful mTLS delivery.

## Planned certificate rotation

Upvest recommends setting up certificates with at least a one-year validity period.

Start planned rotation **three months before expiry** to reduce the risk of delivery disruption. For planned rotation, follow the same process as initial key configuration:

* Generate a new certificate bundle
* Provide environment-specific bundles (sandbox and live)
* Submit bundles securely for review
* Complete integration validation before final cutover


## Emergency certificate rotation

If you suspect that a private key or certificate has been exposed or compromised, perform an emergency rotation immediately.

Contain and assess impact
Treat the key as compromised. Identify affected environments and endpoints, and begin incident handling according to your internal security process.

Generate replacement certificates
Generate a new private key and certificate bundle for each affected environment.

Notify Upvest immediately
Contact Upvest through your established secure support channel and flag the request as an emergency certificate rotation.

Submit new bundles securely
Send the replacement bundles using the agreed secure transfer mechanism, with clear environment labels.

Validate and cut over
Coordinate with Upvest to validate webhook delivery over mTLS and complete cutover to the new certificates.

Revoke and retire old material
Revoke and retire compromised certificates and keys according to your incident response policies.