Verifying webhooks

You can configure the webhooks you use for Video API to be secured with signed callbacks.

The secure callbacks feature provides a method for your application to verify a webhook callback request is coming from Vonage and its payload has not been tampered with during transit. When receiving a request, the incoming callback webhook will include a JWT in the authorization header, which is signed with your signature secret.

Available API callbacks

• Session monitoring — Session monitoring webhook callbacks will be sent to the URL when a Session event is detected.

• Archiving monitoring — Archive callbacks will be sent to provide status events on archive recordings and the resulting files

• Broadcast monitoring — Broadcast callback events will be sent when a Broadcast event is detected (for example, when a Broadcast is created, updated, or destroyed).

• Experience Composer monitoring — Experience composer callback events will be sent when the Experience Composer's status changes.

• Live captions monitoring — Live Captions callback events are sent when live captions start, stop, and fail.

• SIP call monitoring — An HTTP request will be sent to the URL when a SIP call event is detected

Configuring secure callbacks

1. Log in to your Vonage Video API Account.

2. From the left-hand menu, select Applications.

3. For existing projects click on the three dots and select the Edit option and scroll down to the capability section.

4. For new projects the capability section is displayed after clicking on Create a new application.

5. Toggle to enable the video option.

6. A set of inputs will appear, each one offering callbacks for different parts of the API. Provide a proper URL for selected callback inputs. Only then a signature secret button will become toggleable. Click it to enable the callbacks.

A randomly generated signature secret will be provided by the system each time the signature secret field is enabled. This pre-populated signature secret value can be used or overwritten with a user selected value. When receiving a callback, the incoming webhook will be signed with the signature secret configured in the field. Click Save Changes to configure this secret to be used for secure callbacks. (Note: the signature secret must be character string, with a minimum length of 1 character to a maximum length of 50 characters.).

You can enable as many callbacks as you want.

Updates to the URLs and secrets may take up to 30 minutes to apply the configuration in the platform.

Validating secure callbacks

Validating secure callbacks provides a number of security benefits, including:

• The ability to verify a request originates from Vonage

• Ensuring that the message has not been tampered with while in transit

• Defending against interception and later replay

There are two parts to validating secure callbacks:

• Verifying the request

• Verifying the payload (optional)

Verifying the request

Callbacks will include a JWT in the Authorization header. Use the API key included in the JWT claims to identify which of your signature secrets has been used to sign the request. The secret used to sign the request corresponds to the signature secret associated with the api_key included in the JWT claims. You can identify your signature secret through the Vonage Video API Account portal.

Code samples

const express = require('express');
const jwt = require('@vonage/jwt');
const app = express();

app.use(express.json());

// replace VIDEO_SIGNATURE_SECRET with the secret value set at the Dashboard
const VIDEO_SIGNATURE_SECRET = process.env.SIGNATURE_SECRET;

app.post('/video/webhook', express.raw({ type: 'application/json' }), (request, response) => {
  try {
    const payload = request.body;
    const token = request.headers.authorization.split(" ")[1];

    const verified = jwt.verifySignature(token, VIDEO_SIGNATURE_SECRET)
    if (!verified) {
      console.log('tampering detected');
      response.status(401).send();
    }
    console.log('Success');
    return response.status(204).send();
  } catch (err) {
    if (err instanceof JsonWebTokenError  || err instanceof TokenExpiredError){
      console.log('Token Error', err.message);
    } else {
      console.error(err);
    }
    return response.status(401).send();
  }
});

app.listen(4242, () => console.log('Running on port 4242'));

const express = require('express');
const jwt = require('jsonwebtoken');
const sha256 = require('js-sha256');
const app = express();

app.use(express.json());

// replace VIDEO_SIGNATURE_SECRET with the secret value set at the Dashboard
const VIDEO_SIGNATURE_SECRET = process.env.SIGNATURE_SECRET;

app.post('/video/webhook', express.raw({ type: 'application/json' }), (request, response) => {
  try {
    const payload = request.body;
    const token = request.headers.authorization.split(" ")[1];

    const decoded = jwt.verify(
      token,
      VIDEO_SIGNATURE_SECRET,
      { algorithms: ['HS256'] },
      );
    if (!decoded) {
      console.log('tampering detected');
      response.status(401).send();
    }
    console.log('Success');
    return response.status(204).send();
  } catch (err) {
    if (err instanceof JsonWebTokenError  || err instanceof TokenExpiredError){
      console.log('Token Error', err.message);
    } else {
      console.error(err);
    }
    return response.status(401).send();
  }
});

app.listen(4242, () => console.log('Running on port 4242'));

Known Limitations/Considerations

The following section covers limitations and considerations before enabling this feature.

Callback IP address

Once enabled for secure callbacks, the IP Address range used by the Vonage callback service will be of a different set than previous Video API callbacks. Please allow the following range to enable seamless communication with Vonage secure callbacks: 216.147.0.0/18.

Mutual TLS (mTLS)

mTLS is supported in the secure callbacks flow. More information can be found here.

Callback retry and back off policy changes

Once enabled for secure callbacks, there will be a change in behavior for the callback retry and backoff policy.

What will happen if the callback events of my application goes down?

After 24 hours, the individual callback retry logic will stop and the individual callback event will no longer be sent. However, callbacks for new events will continue to be attempted.