The network traffic initiated by Dialogflow for webhook requests
is sent on a public network.
To ensure that traffic is both secure and trusted in both directions,
Dialogflow optionally supports
[Mutual TLS authentication (mTLS)](https://en.wikipedia.org/wiki/Mutual_authentication).
During Dialogflow's standard [TLS handshake](https://hpbn.co/transport-layer-security-tls/#tls-handshake),
your webhook server presents a certificate that can be validated by Dialogflow,
either by following the [Certificate Authority chain](https://hpbn.co/transport-layer-security-tls/#chain-of-trust-and-certificate-authorities)
or by comparing the certificate to a [Custom CA certificate](https://docs.cloud.google.com/dialogflow/cx/docs/concept/custom-ca.md.txt).
By enabling mTLS on your webhook server, it can authenticate
the client certificate presented by Dialogflow
to your webhook server for validation, completing the establishment of mutual
trust.

By default, Dialogflow presents a client certificate issued by
[SSL.com](https://www.ssl.com/) (`CN=Google LLC`).

> [!NOTE]
> **Note:** Until December 1, 2026, Dialogflow temporarily falls back to the legacy Google Trust Services (`CN=*.dialogflow.com`) client certificate if a webhook rejects the SSL.com certificate. If your webhook server already trusts Google Trust Services, you can keep that configuration in place during the transition while adding the SSL.com root certificate. After December 1, 2026, Dialogflow only presents the SSL.com client certificate.

## Requesting mTLS

To request mTLS:

1. Prepare your webhook HTTPS server to request the client certificate during the TLS handshake.
2. Configure your webhook server's mTLS trust store to trust the **SSL.com Root Certification Authority RSA** root certificate, which you can download directly from [SSL.com](https://ssl.com/repo/certs/SSLcomRootCertificationAuthorityRSA.pem):
   - **Root CA:** `SSL.com Root Certification Authority RSA`
   - **SHA-256 fingerprint:** `85:66:6A:56:2E:E0:BE:5C:E9:25:C1:D8:89:0A:6F:76:A8:7E:C1:6D:4D:7D:5F:29:EA:74:19:CF:20:12:3B:69`
   - **Verification depth:** Set the TLS client certificate verification depth to at least `2`. Dialogflow automatically sends the intermediate certificate (`SSL.com Client Certificate Intermediate CA RSA R2`) during the TLS handshake, so you only need to add the root CA to your trust store.
3. Configure your webhook server to verify the client certificate upon receiving
   it. If your server or API gateway allowlists client certificates by subject
   or Common Name (CN), allow the following certificate attributes (the
   certificate doesn't include a Subject Alternative Name (SAN) extension):

   - **Subject:** `C=US, ST=California, L=Mountain View, O=Google, OU=Applied Ai, CN=Google LLC`
   - **Issuer:** `C=US, ST=Texas, L=Houston, O=SSL Corp, CN=SSL.com Client Certificate Intermediate CA RSA R2`

   For stronger validation, match both the full subject and issuer rather than
   `CN` alone.

> [!CAUTION]
> **Caution:** Don't pin the leaf client certificate, as it will be rotated before expiration. Trust the SSL.com root CA instead.

## Sample call to a webhook server using mTLS

This example uses the agent shown in the quickstart with a
[webhook](https://docs.cloud.google.com/dialogflow/cx/docs/concept/webhook.md.txt) server
running
[`openssl`](https://www.openssl.org/docs/manmaster/man1/openssl.html).

1. Sample setup
   1. A Dialogflow ES agent that greets the end user and queries a webhook pointing to a standalone web server.
   2. A private key for TLS communication in a file named `key.pem`.
   3. A certificate chain signed by a [publicly-trusted
      CA (Certificate Authority)](https://docs.cloud.google.com/load-balancing/docs/ssl-certificates/self-managed-certs#use_a_publicly-trusted_ca) in a file named `fullchain.pem`.
   4. The SSL.com root certificate in a file named `SSLcomRootCertificationAuthorityRSA.pem`, downloaded from [SSL.com](https://ssl.com/repo/certs/SSLcomRootCertificationAuthorityRSA.pem).
2. Execute the [`openssl s_server`](https://www.openssl.org/docs/manmaster/man1/openssl-s_server.html) program in the server machine.

   ```console
   sudo openssl s_server -key key.pem -cert fullchain.pem -CAfile SSLcomRootCertificationAuthorityRSA.pem -accept 443 -verify 2
   ```
3. A request is sent to the agent from a client machine. For this example, the request is "Hi". This request can be sent using the Dialogflow Console, or through an API call.
4. Output of [`openssl s_server`](https://www.openssl.org/docs/manmaster/man1/openssl-s_server.html) in the server machine.

   ```
   verify depth is 2
   Using default temp DH parameters
   ACCEPT
   depth=2 C = US, ST = Texas, L = Houston, O = SSL Corporation, CN = SSL.com Root Certification Authority RSA
   verify return:1
   depth=1 C = US, ST = Texas, L = Houston, O = SSL Corp, CN = SSL.com Client Certificate Intermediate CA RSA R2
   verify return:1
   depth=0 C = US, ST = California, L = Mountain View, O = Google, OU = Applied Ai, CN = Google LLC
   verify return:1
   ---BEGIN SSL SESSION PARAMETERS---
   MII...
   ---END SSL SESSION PARAMETERS---
   Client certificate
   ---BEGIN CERTIFICATE---
   MII...
   ---END CERTIFICATE---
   subject=C = US, ST = California, L = Mountain View, O = Google, OU = Applied Ai, CN = Google LLC

   issuer=C = US, ST = Texas, L = Houston, O = SSL Corp, CN = SSL.com Client Certificate Intermediate CA RSA R2

   Shared ciphers:TLS_AES_128_GCM_SHA256:...
   Signature Algorithms: ECDSA+SHA256:...
   Shared Signature Algorithms: ECDSA+SHA256:...
   Peer signing digest: SHA256
   Peer signature type: RSA-PSS
   Supported Elliptic Groups: 0x6A6A:...
   Shared Elliptic groups: X25519:...
   CIPHER is TLS_AES_128_GCM_SHA256
   Secure Renegotiation IS NOT supported
   POST /dialogflowFulfillment HTTP/1.1
   authorization: Bearer ey...
   content-type: application/json
   Host: www.example.com
   Content-Length: 1011
   Connection: keep-alive
   Accept: */*
   User-Agent: Google-Dialogflow
   Accept-Encoding: gzip, deflate, br

   {
     "responseId": "96c0029a-149d-4f5d-b225-0b0bb0f0c8d9-afbcf665",
     "queryResult": {
       "queryText": "Hi",
       "action": "input.welcome",
       "parameters": {
       },
       "allRequiredParamsPresent": true,
       "outputContexts": [{
         "name": "projects/PROJECT-ID/agent/sessions/58ab33f3-b57a-aae9-fb23-8306242d4871/contexts/__system_counters__",
         "parameters": {
           "no-input": 0.0,
           "no-match": 0.0
         }
       }],
       "intent": {
         "name": "projects/PROJECT-ID/agent/intents/399277d6-2ed7-4329-840d-8baa0f60480e",
         "displayName": "Default Welcome Intent"
       },
       "intentDetectionConfidence": 1.0,
       "languageCode": "en",
       "sentimentAnalysisResult": {
         "queryTextSentiment": {
           "score": 0.2,
           "magnitude": 0.2
         }
       }
     },
     "originalDetectIntentRequest": {
       "source": "DIALOGFLOW_CONSOLE",
       "payload": {
       }
     },
     "session": "projects/PROJECT-ID/agent/sessions/58ab33f3-b57a-aae9-fb23-8306242d4871"
   }ERROR
   shutting down SSL
   CONNECTION CLOSED
         
   ```

## Best Practice

To make sure that webhook requests are initiated from your own Dialogflow agents,
you should verify the Bearer
[service identity token](https://docs.cloud.google.com/dialogflow/cx/docs/concept/webhook.md.txt#id-token)
from the request's Authorization header. Alternatively, you can verify a session
parameter provided previously by an authentication server on your side.

## Errors

If the client certificate validation fails
(for example, the webhook server does not trust the client certificate),
the TLS handshake fails and the session terminates.

Common error messages:

| Error message | Explanation |
|---|---|
| Failed to verify client's certificate: x509: certificate signed by unknown authority | Dialogflow sends its client certificate to the external webhook, but the external webhook cannot verify it. Make sure your webhook trust store includes the SSL.com Root Certification Authority RSA root certificate and that your server's verification depth is at least 2. |