{"_id":"5dbc647985d2460011581854","project":"564e5930c3553e0d003e53d0","version":{"_id":"564e5a9b1560880d008d30dc","project":"564e5930c3553e0d003e53d0","__v":27,"createdAt":"2015-11-19T23:26:19.166Z","releaseDate":"2015-11-19T23:26:19.166Z","categories":["564e5a9b1560880d008d30dd","566318e1f5ca460d00f41896","56631d08cd54d50d005015fa","56631d2a81ad7417006a202c","5668ba19fbd7680d009375f4","5668cb8b10bda80d00797ed9","5668cb9d10bda80d00797eda","56830d8a3f94e00d004e2a7a","56830d9072bb720d0091f594","56830d94cb4d190d0027698e","56830dc44aecbd0d00a464c5","569e90f3c9b43e0d00c4bab1","56a96d338791090d00113bab","56b12d8336d2580d00247877","56c36bf0a869d017002ea55b","56c36bf93d30210d00ea84bb","56c77749b935671700ff0304","56c7ab9e5652c217008e091a","56cb8bdad5c6241d00ef5e61","58aefce02470660f00b54539","58aefd0bebd7370f0078b954","59ca65ca4337830026edf24f","5c33cd9eb47ba20051ac8d64","5c33df728bec1d0063431c34","5c4783ef523219027055513a","5c4f35033400f3010203a999","5d1d0c9f19c3a0003aeb525a"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Foundation","version_clean":"2.0.0","version":"2"},"category":{"_id":"56c7ab9e5652c217008e091a","pages":["56c7ace6606ee717003c475d","56d3d6390b39260b008da477"],"project":"564e5930c3553e0d003e53d0","version":"564e5a9b1560880d008d30dc","__v":2,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-19T23:56:14.582Z","from_sync":false,"order":7,"slug":"webhooks","title":"Webhooks"},"user":"59e10aa4bf9ac7001a235dd6","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2019-11-01T16:59:37.809Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":999,"body":"# Mutual TLS and Webhooks\n\n## Why use Mutual TLS with webhooks?\n\nMutual TLS builds upon normal TLS by adding client authentication in addition to server authentication to let you verify that webhooks you receive actually came from PagerDuty.\n\n## How it works\n\nIf you specify an HTTPS endpoint for your webhook, PagerDuty will verify your server's certificate to ensure that we are communicating with your server. (See details below)\n\nTo take advantage of mutual TLS, you can configure your server to verify PagerDuty's client certificate. (See steps below)\n\n## Steps to verify PagerDuty's client certificate\n\nThese steps assume you already have server authentication setup.\n\nIn general, there are five steps needed to turn on client authentication for your server:\n1. Download the PEM version of the [DigiCert Global Root CA](https://www.websecurity.symantec.com/content/dam/websitesecurity/support/digicert/symantec/root/DigiCert_Global_Root_CA.pem) certificate.\n2. Turn on client certificate verification.\nSpecify the CA certificate from 1 as trusted.\n3. Set the verification depth to 2 since our PagerDuty certificate is actually signed by the [DigiCert SHA2 Secure Server CA](https://dl.cacerts.digicert.com/DigiCertSHA2SecureServerCA.crt) which is an intermediate CA under DigiCert Global Root CA.\n4. Verify the client certificate is actually from PagerDuty by inspecting its Subject Domain Name.\n\nNow we will go over sample server configurations for NGINX and Apache.\n\n### NGINX\n\n```\nserver {\n\n    listen 443 ssl default_server;\n    # ... existing SSL configuration for server authentication ...\n\n    ssl_verify_client on;\n    ssl_client_certificate /path/to/DigiCert_Global_Root_CA.pem;\n    ssl_verify_depth 2;\n\n    location / {\n        if ($ssl_client_s_dn != \"CN=webhooks.pagerduty.com,O=PagerDuty Inc,L=San Francisco,ST=California,C=US\") {\n            return 403;\n        }\n\n        # ... existing location configuration ...\n    }\n}\n```\n\nFor more info, see http://nginx.org/en/docs/http/ngx_http_ssl_module.html.\n\n### Apache\n\n```\nListen 443\n<VirtualHost *:443>\n    # ... existing SSL configuration for server authentication ...\n\n    SSLVerifyClient require\n    SSLCACertificateFile \"/path/to/DigiCert_Global_Root_CA.pem\"\n    SSLVerifyDepth 2\n</VirtualHost>\n\n<Directory /var/www/>\n    Require expr \"%{SSL_CLIENT_S_DN_CN} == 'webhooks.pagerduty.com'\"\n\n    # ... existing directory configuration ...\n</Directory>\n```\n\nFor more info, see https://httpd.apache.org/docs/2.4/ssl/ssl_howto.html#accesscontrol and https://httpd.apache.org/docs/2.4/mod/mod_ssl.html.\n\n## PagerDuty's Server Verification\n\n### Trusted Root Certificates\n\nPagerDuty supports [Mozilla’s list of included CA Certificates](https://wiki.mozilla.org/CA/Included_Certificates) (HTML or CSV list available). We will drop webhooks if your certificate is self-signed or if your certificate uses a CA outside of this list.\n\nNote: At this time, PagerDuty can only properly verify server certificate chains which are presented in order. Out of order chains will be rejected and result in dropped webhooks. You can test yours using the OpenSSL command below and looking at the numbers / order in the certificate chain in the output.\n\n### Supported TLS Versions\n\nPagerDuty’s webhook delivery system supports only TLS v1.2.\n\n### Supported Cipher Suites\n\n```\nTLS_EMPTY_RENEGOTIATION_INFO_SCSV\nTLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384\nTLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384\nTLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384\nTLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384\nTLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384\nTLS_ECDH_RSA_WITH_AES_256_GCM_SHA384\nTLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384\nTLS_ECDH_RSA_WITH_AES_256_CBC_SHA384\nTLS_DHE_RSA_WITH_AES_256_GCM_SHA384\nTLS_DHE_DSS_WITH_AES_256_GCM_SHA384\nTLS_DHE_RSA_WITH_AES_256_CBC_SHA256\nTLS_DHE_DSS_WITH_AES_256_CBC_SHA256\nTLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256\nTLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256\nTLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256\nTLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256\nTLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256\nTLS_ECDH_RSA_WITH_AES_128_GCM_SHA256\nTLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256\nTLS_ECDH_RSA_WITH_AES_128_CBC_SHA256\nTLS_DHE_RSA_WITH_AES_128_GCM_SHA256\nTLS_DHE_DSS_WITH_AES_128_GCM_SHA256\nTLS_DHE_RSA_WITH_AES_128_CBC_SHA256\nTLS_DHE_DSS_WITH_AES_128_CBC_SHA256\nTLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA\nTLS_ECDHE_RSA_WITH_AES_256_CBC_SHA\nTLS_DHE_RSA_WITH_AES_256_CBC_SHA\nTLS_DHE_DSS_WITH_AES_256_CBC_SHA\nTLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA\nTLS_ECDH_RSA_WITH_AES_256_CBC_SHA\nTLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA\nTLS_ECDHE_RSA_WITH_AES_128_CBC_SHA\nTLS_DHE_RSA_WITH_AES_128_CBC_SHA\nTLS_DHE_DSS_WITH_AES_128_CBC_SHA\nTLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA\nTLS_ECDH_RSA_WITH_AES_128_CBC_SHA\n```\n\n### Testing your connection\n\nUse a tool like [SSL Labs](https://www.ssllabs.com/ssltest/) or OpenSSL to verify that your certificate is valid and working.\n\nFrom [OpenSSL Cookbook](https://www.feistyduck.com/library/openssl-cookbook/online/ch-testing-with-openssl.html):\n```\nopenssl s_client -connect www.pagerduty.com:443\n```","excerpt":"","slug":"webhooks-mutual-tls","type":"basic","title":"Webhooks: Mutual TLS"}

Webhooks: Mutual TLS


# Mutual TLS and Webhooks ## Why use Mutual TLS with webhooks? Mutual TLS builds upon normal TLS by adding client authentication in addition to server authentication to let you verify that webhooks you receive actually came from PagerDuty. ## How it works If you specify an HTTPS endpoint for your webhook, PagerDuty will verify your server's certificate to ensure that we are communicating with your server. (See details below) To take advantage of mutual TLS, you can configure your server to verify PagerDuty's client certificate. (See steps below) ## Steps to verify PagerDuty's client certificate These steps assume you already have server authentication setup. In general, there are five steps needed to turn on client authentication for your server: 1. Download the PEM version of the [DigiCert Global Root CA](https://www.websecurity.symantec.com/content/dam/websitesecurity/support/digicert/symantec/root/DigiCert_Global_Root_CA.pem) certificate. 2. Turn on client certificate verification. Specify the CA certificate from 1 as trusted. 3. Set the verification depth to 2 since our PagerDuty certificate is actually signed by the [DigiCert SHA2 Secure Server CA](https://dl.cacerts.digicert.com/DigiCertSHA2SecureServerCA.crt) which is an intermediate CA under DigiCert Global Root CA. 4. Verify the client certificate is actually from PagerDuty by inspecting its Subject Domain Name. Now we will go over sample server configurations for NGINX and Apache. ### NGINX ``` server { listen 443 ssl default_server; # ... existing SSL configuration for server authentication ... ssl_verify_client on; ssl_client_certificate /path/to/DigiCert_Global_Root_CA.pem; ssl_verify_depth 2; location / { if ($ssl_client_s_dn != "CN=webhooks.pagerduty.com,O=PagerDuty Inc,L=San Francisco,ST=California,C=US") { return 403; } # ... existing location configuration ... } } ``` For more info, see http://nginx.org/en/docs/http/ngx_http_ssl_module.html. ### Apache ``` Listen 443 <VirtualHost *:443> # ... existing SSL configuration for server authentication ... SSLVerifyClient require SSLCACertificateFile "/path/to/DigiCert_Global_Root_CA.pem" SSLVerifyDepth 2 </VirtualHost> <Directory /var/www/> Require expr "%{SSL_CLIENT_S_DN_CN} == 'webhooks.pagerduty.com'" # ... existing directory configuration ... </Directory> ``` For more info, see https://httpd.apache.org/docs/2.4/ssl/ssl_howto.html#accesscontrol and https://httpd.apache.org/docs/2.4/mod/mod_ssl.html. ## PagerDuty's Server Verification ### Trusted Root Certificates PagerDuty supports [Mozilla’s list of included CA Certificates](https://wiki.mozilla.org/CA/Included_Certificates) (HTML or CSV list available). We will drop webhooks if your certificate is self-signed or if your certificate uses a CA outside of this list. Note: At this time, PagerDuty can only properly verify server certificate chains which are presented in order. Out of order chains will be rejected and result in dropped webhooks. You can test yours using the OpenSSL command below and looking at the numbers / order in the certificate chain in the output. ### Supported TLS Versions PagerDuty’s webhook delivery system supports only TLS v1.2. ### Supported Cipher Suites ``` TLS_EMPTY_RENEGOTIATION_INFO_SCSV TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS_DHE_RSA_WITH_AES_256_CBC_SHA TLS_DHE_DSS_WITH_AES_256_CBC_SHA TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDH_RSA_WITH_AES_256_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_DHE_RSA_WITH_AES_128_CBC_SHA TLS_DHE_DSS_WITH_AES_128_CBC_SHA TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDH_RSA_WITH_AES_128_CBC_SHA ``` ### Testing your connection Use a tool like [SSL Labs](https://www.ssllabs.com/ssltest/) or OpenSSL to verify that your certificate is valid and working. From [OpenSSL Cookbook](https://www.feistyduck.com/library/openssl-cookbook/online/ch-testing-with-openssl.html): ``` openssl s_client -connect www.pagerduty.com:443 ```