Custom CA certificates

Conversational Agents (Dialogflow CX) webhooks require HTTPS endpoints that present valid TLS certificates when they are verified using Google's default trust store. However, you may want to use custom CA certificates, which cannot be signed by a certificate authority recognized by Google's default trust store. For example, webhook servers that are inside Google's private VPC network have this issue. In this case, you can upload the custom certificates to Conversational Agents (Dialogflow CX) when creating webhooks, and the uploaded certificates will override Google's default trust store.

Custom CA certificates can be self-signed certificates or custom root certificates. You can upload multiple certificates in case you want to rotate the certificates. The certificates must be in DER format and must be signed with subject alternative name matching the webhook URL. When the keyUsage extension is present, its value needs to be digitalSignature.

Demo self-signed server

The following is the configuration of a demo server:

  1. Prepare self-signed certificate files. We use www.example.com as the example domain.
    openssl genrsa -out server.key 2048
    openssl req -nodes -new -sha256 -newkey rsa:2048 -key server.key -subj "/CN=www.example.com" -out server.csr
    openssl x509 -req -days 3650 -sha256 -in server.csr -signkey server.key -out server.crt -extfile <(printf "\nsubjectAltName='DNS:www.example.com'")
    openssl x509 -in server.crt -out server.der -outform DER
  2. Start your HTTPS server using the server certificate (server.crt) and private key (server.key) created in previous step. We assume the server is listening on port 443.
  3. Test to connect to the server locally.
    curl --cacert server.crt https://www.example.com --resolve www.example.com:443:127.0.0.1

Demo webhook with custom certificate

After you have setup the server with your custom certificate, you may create a webhook resource with the following extra instructions to use the custom certificate:

  • Set the URL matching the domain signed with the certificate (https://www.example.com in previous demo). It is your own responsibility to make sure that your domain will correctly resolve to the IP address of the server.
  • Upload the custom certificate in DER format. This is the server.der file in previous self-signed demo or the custom root certificate.
  • For webhooks integrated with Service Directory private network access, Setup your Service Directory Endpoint with the IP address and port of your server, and provide the Service Directory Service when creating webhook.