# 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. 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](#method-1-client-generates-the-certificates): You create the required certificates and provide them to Upvest to implement. * [Upvest generates certificate/signed by DigiCert](#method-2-upvest-generates-certificatesigned-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](#method-3-upvest-generates-certificatesigned-by-client): Upvest creates the required certificates and provides them directly to the client. ## 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 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. ## Initial key configuration Choose the mTLS method that matches your setup, then follow the steps below. ### Method 1: Client generates the certificates 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. ### Method 2: Upvest generates certificate/signed by DigiCert 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. ### Method 3: Upvest generates certificate/signed by client 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. ## Planned certificate rotation 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 ## 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.