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). During Dialogflow's standard TLS handshake, your webhook server presents a certificate that can be validated by Dialogflow, either by following the Certificate Authority chain or by comparing the certificate to a Custom CA certificate. 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 (CN=Google LLC).
Requesting mTLS
To request mTLS:
- Prepare your webhook HTTPS server to request the client certificate during the TLS handshake.
- 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:
- 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.
- Root CA:
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
CNalone.- Subject:
Sample call to a webhook server using mTLS
This example uses the agent shown in the quickstart with a
webhook server
running
openssl.
- Sample setup
- A Dialogflow CX agent that takes shirt orders, and sends them to a webhook pointing to a standalone web server.
- A private key for TLS communication in a file named
key.pem. - A certificate chain signed by a
publicly-trusted
CA (Certificate Authority) in a file named
fullchain.pem. - The SSL.com root certificate in a file named
SSLcomRootCertificationAuthorityRSA.pem, downloaded from SSL.com.
-
Execute the
openssl s_serverprogram in the server machine.sudo openssl s_server -key key.pem -cert fullchain.pem -CAfile SSLcomRootCertificationAuthorityRSA.pem -accept 443 -verify 2 - A request is sent to the agent from a client machine. For this example, the request is "I want to buy a large red shirt". This request can be sent using the Dialogflow Console, or through an API call.
-
Output of
openssl s_serverin 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: 0xEAEA:... Shared Elliptic groups: X25519:... CIPHER is TLS_AES_128_GCM_SHA256 Secure Renegotiation IS NOT supported POST /shirts-agent-webhook HTTP/1.1 authorization: Bearer ey... content-type: application/json Host: www.example.com Content-Length: 1595 Connection: keep-alive Accept: */* User-Agent: Google-Dialogflow Accept-Encoding: gzip, deflate, br { "detectIntentResponseId": "a7951ce2-2f00-4af5-a508-4c2cb45698b0", "intentInfo": { "lastMatchedIntent": "projects/PROJECT_ID/locations/REGION/agents/AGENT_ID/intents/0adebb70-a727-4687-b8bc-fbbc2ac0b665", "parameters": { "color": { "originalValue": "red", "resolvedValue": "red" }, "size": { "originalValue": "large", "resolvedValue": "large" } }, "displayName": "order.new", "confidence": 0.9978873 }, "pageInfo": { "currentPage": "projects/PROJECT_ID/locations/REGION/agents/AGENT_ID/flows/00000000-0000-0000-0000-000000000000/pages/06e6fc4d-c2f2-4830-ab57-7a318f20fd90", "displayName": "Order Confirmation" }, "sessionInfo": { "session": "projects/PROJECT_ID/locations/REGION/agents/AGENT_ID/sessions/session-test-001", "parameters": { "color": "red", "size": "large" } }, "fulfillmentInfo": { "tag": "confirm" }, "messages": [{ "text": { "text": ["Ok, let\u0027s start a new order."], "redactedText": ["Ok, let\u0027s start a new order."] }, "responseType": "ENTRY_PROMPT", "source": "VIRTUAL_AGENT" }, { "text": { "text": ["You have selected a large, red shirt."], "redactedText": ["You have selected a large, red shirt."] }, "responseType": "HANDLER_PROMPT", "source": "VIRTUAL_AGENT" }], "text": "I want to buy a large red shirt", "languageCode": "en" }ERROR shutting down SSL CONNECTION CLOSED
Custom Client Certificate
Custom client certificates can be configured at an agent level to be used by all webhooks. At the time of webhook invocation, the configured certificates will be presented during the handshake.
The private key and passphrase are configured as a Secret Manager resource. The Dialogflow service agent will need to be given Secret Manager Secret Accessor permissions to the secret.
The client certificates need to be signed by a Certificate Authority for the handshake to be successful.
Best Practice
To make sure that webhook requests are initiated from your own Dialogflow agents, you should verify the Bearer service identity 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. |