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