Skip to main content

Webhook Certificate Validation

Overview#

When subscribing to a Novos webhook (i.e. ESL or priceDB update) it's recommended that the subscriber provide a secure HTTPS URL for the endpoint of the webhook. One of the benefits of using TLS on the webhook URLs is that the endpoint can be authenticated using the chain of trust provided by the TLS certificate. This section discusses how Novos interacts with the certificates presented when TLS handshake is performed during webhook calls and how this behavior can modified based on customer requirements.

Default Certificate Validation Behavior#

When Novos then makes the call to a webhook using the HTTPS scheme, the default action is to validate the authenticity of the TLS certificate presented by webhook peer during the TLS handshake against the system/platform trust store. If the platform trusts the certificate, Novos will execute the webhook call to the peer. If the certificate cannot be validated against the root certificates in the platform trust store Novos will not execute the webhook call.

Configuration of Certificate Validation#

To accommodate situations where a certificate from a Certificate Authority (CA) trusted by the platform is not available Novos provides the ability to configure how certificates are validated. A typical example of when this configuration is used would be a webhook endpoint on a non-public server such that a certificate from a well known CA such as LetsEncrpyt cannot be obtained and the server presents Novos with a self-signed certificate. Normally Novos would fail to validate the self-signed certificate.

Webhook TSL certificate validation configuration is implemented using webhookCertTrustPolicy keyword in novosserver.properties. There are three values available for the keyword, SYSTEM, ALL and CERTLIST. If the keyword is not present or set to any value other than SYSTEM, ALL or CERTLIST Novos will behave as if it was set to SYSTEM.

webhookCertTrustPolicy=SYSTEM

The default setting is SYSTEM and tells Novos to validate certificates using the system trust store. 

webhookCertTrustPolicy=ALL

Novos will accept any certificate presented during the TLS handshake. No validation will be performed. This is the least secure setting for webhookCertTrustPolicy as the authenticity of the webhook URL cannot be established. Depending on the threat profile of the webhook client this may be acceptable as the established TLS connection is still cryptographically sound.

webhookCertTrustPolicy=CERTLIST

CERTLIST allows you to provide Novos with a list of certificates which should be used in place of the system trust store to validate webhook client certificates. If webhookCertTrustPolicy is set to CERTLIST, Novos expects to find the additional keyword webhookCertTrustCerts in novosserver.properties. Novos will not start if webhookCertTrustPolicy is set to CERTLIST and webhookCertTrustCerts is not set or cannot be processed successfully. For the format of webhookCertTrustCerts see below. 

webhookCertTrustCerts=s<certificate list\>

webhookCertTrustCerts provides Novos with a list of certificates which are used in place of the system trust store when performing validation of certificates presented by webhook clients. The format of the value of this keyword is a comma seperated list of DER encoded, PEM formatted X509 certificate file names. For example:

webhookCertTrustCerts=cert1.pem, cert2.pem, cert3.pem

In the example there are 3 certificates specified. Novos will load each certificate into a list of certificates, each of which will be checked when doing TLS certificate validate. If a certificate in the list is found that will validate the webhook client certificate, Novos will make the webhook call. If client webhook certificate will not validate against any of the certificates in the list, Novos will not proceed with the webhook call.

Certificate file names can be fully qualified path names (i.e. c:\certs\ca.cert.pem or /etc/ssl/certs/ca.cert.pem) or can be just file names as in the above example. If the file name doesn't include a path the certificate(s) must be in the Novos home directory. The Novos home directory is the same place where novosserver.properties is located.

Note: On Windows platforms where the path seperator is a backslash '\', fully qualified certificate file names must use 2 backslashes for the path seperator to avoid treating the path seperator as the start of an escape sequence.