Secure Callbacks

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 token in the authorization header, which is signed with your signature secret.

The following API callbacks can be secured with signed callbacks and configured with their own signature secret:

• Session monitoring — Monitor session activity by registering a callback URL. Session monitoring webhook callbacks will be sent to the URL when a Session event is detected.

• Archiving monitoring — Monitor archive status by registering a callback URL. Archive callbacks will be sent to provide status events on archive recordings and the resulting files

• SIP call monitoring — Monitor SIP call activity by registering a callback URL. An HTTP request will be sent to the URL when a SIP call event is detected

• Experience Composer monitoring — Monitor Experience Composer activity by registering a callback URL. Experience composer callback events will be sent when the Experience Composer's status changes.

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

• Live captions monitoring — Monitor Live Captions activity by registering a callback URL. Live Captions callback events are sent when live captions start, stop, and fail.

Configuring secure callbacks

The following instructions can be used to enable Session Monitoring a secure callback. You can also follow these instructions similarly for other callbacks (for archive monitoring, SIP call monitoring, and experience composer monitoring).

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. The user interface includes options to configure the callback URL and (optionally) a signature secret.

7. 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.).

83w. The system will report that secure callbacks have been configured with the URL and signature secret. Note that updates 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.

Verify the payload has not been tampered with in transit

Once you have verified the authenticity of the request, you may optionally verify the request payload has not been tampered with by comparing a SHA-256 hash of the payload to the payload_hash field found in the JWT claims. If they do not match, then the payload has been tampered with during transit. You only need to verify the payload if you are using HTTP rather than HTTPS, as Transport Layer Security (TLS) prevents MITM attacks.

Code sample

The following Express example shows how to verify a webhook signature. It is recommended you use HTTPS protocol as it ensures that the request and response are encrypted on both the client and server ends.

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.

TLS Mutual Authentication no longer applicable

Once enabled for secure callbacks, ‘TLS Mutual Authentication for HTTPs connection’ covered in this support article is no longer applicable and should not be used.

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?

• Previous behavior: Vonage will retry 4 times for each event that we fail to deliver to the application server.

  For Session Monitoring Only - If the platform detects 50 delivery failures within a 30 minutes time frame, the event forwarding was disabled for Session monitoring callbacks. A notification email was sent to the customer to notify that callbacks were disabled. To re-enable event forwarding, the Session monitoring callback URL needed to be configured again via the Vonage Video API Account Portal.

• New behavior: 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.