Authenticating Callback Events for Video API Authenticating Callback Events for Video API

Authenticating Callback Events for Video API

Richard Sabbarton

Objective

Authenticating or verifying delivered callback (webhook) events.

Applies To

  • Webhook
  • Callback
  • Vonage Video API

How to recognise if I'm using Vonage Video API Unified Environment or Vonage Video API OpenTok environment?

Verifying Secure Callbacks

The Vonage Video API (OpenTok) Platform offers various ways to authenticate the callback (Webhook) events delivered from our servers. Secure callbacks are enabled by default in the Vonage Video Opentok and Unified environments. Customer will have to configure their signature secret in the respective settings. The secure callbacks feature provides a method for your application to verify a webhook callback request is coming from Vonage and that its payload has not been tampered with during transit. When receiving a request, the incoming callback webhook will include a JWT token in the authorization header, which is signed with your signature secret.

 

Enabling Secured callbacks on the Vonage Video Opentok Environment 

 

 

Enabling Secure Callbacks using the Vonage Video API Unified Environment

Enabling HTTPS instead of HTTP

Customers may choose to receive the events delivered over plain HTTP. However, we recommend using HTTPS where possible for better security and authenticity. However, you can choose to combine HTTP with IP Whitelisting.

Enabling TLS Mutual Authentication for HTTPS connections

TLS Mutual Authentication (mTLS) for HTTPs connection is supported for secured callbacks. 

OpenTok Platform supports TLS mutual authentication for additional security, where customers’ servers can authenticate and verify the identity of the various TokBox servers that invoke Webhooks.

During the SSL Handshake, the customer’s HTTPS server must request a Client Certificate by sending the Certificate Request message. Since Certificate Request is an optional SSL handshake message, you’d need to make configuration changes to enable it.

OpenTok Client Certificate

The customer's HTTPS server may choose to verify the fingerprint of the received certificate. Please contact the Support Team for the latest OpenTok certificate fingerprints.

Configuring the TLS Mutual Authentication for Nginx

(Similar instructions should apply to other HTTP servers.)

The following configuration in nginx.conf will enable TLS Mutual authentication. The parameter ssl_verify_client should be set to on. Please have a look at the Nginx wiki for additional configuration parameters.

ssl_client_certificate /home/tokbox/client_ca_root.pem;
ssl_verify_client on;
ssl_verify_depth 10;

Configuring the CA Certificate Chain

You need to create a PEM file with DigiCert's (OpenTok's certificate CA) CA certificate and point ssl_client_certificate to it. For additional intermediate CA certificates not sent by the Client, you should prepend them to the PEM file. The ssl_verify_depth can usually be set to the number of intermediate CA certificates the client certificate chain has or simply how deep the certificate chain is from the end (or server) certificate to the trusted Root CA certificate. It is usually safer to keep a maximum of 10.

CA Certificates

Currently, the OpenTok Client certificate chain has the following Intermediate and Root CA certificates: 

These are DER (Binary formatted) certificates. You can convert these to PEM (Base-64) format and append each other in a single file (the first being intermediate, followed by CA).

Implementing Secure Client Verification

Nginx (or similar) servers will verify whether the received certificate can be trusted. As part of that, the Customer’s HTTPS server should validate the Client's hostname or domain name. The domain name received as part of the certificate can be verified by comparing it against the pre-configured domain name.

If Nginx is used as a proxy server, often terminating the SSL connections, you could set custom proxy headers with necessary attributes from the client certificate, which the application logic will eventually validate.

With the following configuration, Nginx will populate the $ssl_client_s_dn variable with the Subject DN (Distinguished Name) present in the client certificate. This value can be parsed and manually compared by the application logic to verify that the domain matches. Refer to Nginx wiki.

Alternatively, you could verify the DN in the Nginx config file without delegating to application logic; refer to the Nginx documentation.

server {
   ssl_client_certificate /srv/ssl/self.crt;
   ssl_verify_depth 10;
   ssl_verify_client on;
   proxy_set_header X-SSL-Client-Subject-DN $ssl_client_s_dn;
}

Cipher Suites

While our servers support various Cipher suites to cater to many types and configurations of HTTPS servers, customers can verify whether their HTTPS endpoint is compatible by testing the HTTPS URL via Account Portal.

IP Whitelisting

In addition to verifying the certificate, customers could choose to whitelist the IP addresses that are used to send these callback events. Please allow the following range to enable seamless communication with Vonage secure callbacks: 216.147.0.0/18. (Note: This address is now part of IP whitelist)

Callback Retry Mechanism and backoff policies

The secure callback services will follow a retry and backoff policy to try and deliver any individual callback (e.g. archiveStopped, archiveAvailable, etc.) of any type (Session Monitoring, Archiving, SIP, Captions or Experience Composer) for up to 24 hours. After 24 hours, the individual callback retry logic will stop, and the individual callback event will no longer be sent. The retry logic strategy is based on exponential backoff (the wait doubles before each retry). The initial backoff retry is 5 seconds, and then the time between retries doubles each time, increasing to every 15 min until 24 hours is reached. Additionally, the callback retry would be only enabled for connection error (5xx) or connection timeout.

      1. initial_back_off: 5 seconds
      2. max_back_off: 15 minutes
      3. max_retry_time: 24 hours

Important: The service will not disable event forwarding in the case of excessive delivery failures since the retry and backoff mechanism will be used. Therefore, there will not be any expected email notification to notify that callbacks were disabled and need to be re-enabled because the new service will not suspend/disable callbacks in any way.

Troubleshooting

Please contact the Support Team for additional assistance with troubleshooting.

Articles in this section