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.
Upvest offers three approaches to implement mTLS. You can select the method that works best for your setup. We describe the process for each approach in the sections below.
- Clients generate certificates: You create the required certificates and provide them to Upvest to implement.
- Upvest generates certificate/signed by DigiCert: Upvest creates the required certificates and uses our Certificate Authority (CA) provider, DigiCert, to provide them to the client.
- Upvest generates certificate/signed by client: Upvest creates the required certificates and provides them directly to the client.
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 if you are generating your own certificates:
- 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.
Choose the mTLS method that matches your setup, then follow the steps below.
Follow the steps below to generate and provide the required certificates to Upvest.
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
You can send the bundles directly to the Upvest security team or work with your Upvest account manager to deliver the files.
Upvest review and confirmation
Upvest reviews and securely stores the bundles, then confirms when integration testing can begin.
Integration and validation
You can start integration testing by calling our /test webhook endpoint and confirm successful webhook integration testing.
Follow the steps below to receive and process the required certificates via Upvest's Certificate Authority (CA) provider, DigiCert.
Upvest generates a certificate signing request (CSR)
Upvest generates a certificate signing request (CSR) that contains the public key and Upvest's identifying details (our organisation name, our locality/country, and our webhook's website address).
Upvest provides the CSR to DigiCert
Upvest provides the CSR to DigiCert.
Upvest review and confirmation
Upvest reviews and securely stores the file from DigiCerts. We then send the certificates to the client and confirm when integration testing can begin.
Integration and validation
You can start integration testing by calling our /test webhook endpoint and confirm successful webhook integration testing.
Follow the steps below to receive and process the required certificates directly from Upvest.
Upvest generates the certificate bundle
Upvest generates a Certificate Signing Request (CSR) file that contains the public key and Upvest's identifying details (our organization name, our locality/country and our webhook's website address).
Upvest provides the CSR file to the client
Upvest provides the CSR file to the client for processing.
You sign the CSR and deliver the certificate
Process the CSR with your private certificate authority (CA), then send the signed certificate to Upvest.
Upvest review and confirmation
Upvest reviews and securely stores certificates, then confirms when integration testing can begin.
Integration and validation
You can start integration testing by calling our /test webhook endpoint and confirm successful webhook integration testing.
When generating the certificates, Upvest configures then with a one-year validity period. For clients that generate their own certificates, Upvest also 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.