Webhooks
There are several types of webhooks. When you subscribe to webhooks, you will receive all the webhooks we offer at a single URL that you specify. All webhook types are listed in this documentation, and more are added periodically. You can safely ignore the types of webhooks you're not interested in (returning an HTTP 2xx status; see below), and only process the webhooks that interest you. For the specific type of webhook you're interested in, please review the documentation specific to that webhook. This document describes how you should receive and respond to SecureVideo webhooks.
Your webhook URL must be HTTPS, and cannot be HTTP. Once your webhook URL has been set up by SecureVideo support, e.g., https://someapp.mytelehealthsite.com/SecureVideoWebhook, SecureVideo will immediately begin publishing webhooks to that URL via the HTTPS POST method. The content of the HTTPS POST will always be JSON, with the following properties:
{ "WebhookType": "SOME_TYPE", "ID": 12345, "Status": "SOME_STATUS", "EventTs": "2019-06-11T10:45:12", "Attributes": [
{ "AttributeName": "SomeAttribute", "AttributeValue": "ValueOfTheAttribute" },
{ "AttributeName": "SomeOtherAttribute", "AttributeValue": "ValueOfTheOtherAttribute" },... ] }
This payload structure is flexible in that it allows you to use a single parsing method for all webhook types. EventTs will be the date/time in UTC that the original event was fired. In the event you do not wish to act on a webhook if it is older than a certain age, you can compare the EventTs to your current system time UTC to ignore a webhook which is too old. Depending on the WebhookType, ID and Status may mean different things, and the array of attributes will have different attribute names. If no attributes are used for the Webhook Type (e.g., there are no attributes sent for the SESSION_STATUS webhook type) then the Attributes property is omitted. These specifics are all documented in the article specific to the webhook you are trying to implement.
Webhook Authentication
When you receive a webhook to your webhook URL, there will be a Basic Authorization header in the webhook request headers. You can use this Authorization header to validate that the request came from SecureVideo. The Authorization header will contain exactly the same value as the one you would use to send any request to the SecureVideo API; see Getting Started with the SecureVideo API for details on how to compute this value.
Here is an example Authorization Header: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Webhook Retry Intervals
For robustness, the webhooks have an expanding retry interval built into them. We send the initial webhook immediately upon an event occurring. If we receive an HTTP 2xx response, then we assume that the webhook was processed successfully by you, and we do not re-send it. If we receive any HTTP response code which is not 2xx, we queue the webhook for retry according to the following schedule:
- First Retry - 2 minutes
- Second Retry - 5 minutes
- Third Retry - 15 minutes
- Fourth Retry - 1 hour
- Fifth Retry - 6 hours
- Sixth and Final Retry - 1 day
These intervals are not exact, but will generally be plus/minus 1 minute. If a webhook arrives so late that it should be considered moot, you can know this by comparing the current date/time in UTC to the EventTs property in the webhook. The webhook retry intervals apply to all customers and are not customizable. They are designed to provide reasonable retry intervals for both time-sensitive events which could quickly become moot (e.g., e-mail event for an on demand session) and less time-sensitive events which require more robust notification (e.g., e-mail event for a future scheduled session), as well as to contemplate different retry causes (e.g., short-term issue such as a server temporarily down vs. a longer-term issue such as a network outage at a customer data center).
General Webhook Test Trigger
To generally test your ability to consume a SecureVideo webhook, once your webhook URL has been established you can login to your API tab and at the bottom click the button "Test Webhook". This will send the following webhook as an HTTPS POST to your webhook URL:
{ "WebhookType": "TEST_WEBHOOK", "ID": 12345, "Status": "TEST", "EventTs": "2019-06-11T10:45:12", "Attributes": [
{ "AttributeName": "CustomerId", "AttributeValue": "12345" },
{ "AttributeName": "CurrentTimeUtc", "AttributeValue": "2019-06-11T22:45:05" } ] }
In the test webhook, the ID you receive will be the number of seconds since January 1, 1970 (to ensure your system can handle an ID which is a 32-byte integer). The CurrentTimeUtc attribute, like all times in the SecureVideo API, will be given in UTC and use ISO time format without time zone, and the CustomerId attribute will be your SecureVideo customer ID. To work most easily with typical Javascript deserialization tools, in the attributes array all properties will be strings, even if you will immediately cast them to integers or dates.
If you would like only to verify the test webhook, you can set up a webhook viewer at a free third-party webhook tester site, such as https://webhook.site. (You can e-mail this webhook testing site to SecureVideo support, and use this as your initial endpoint to verify the webhook payloads you will be receiving.)
This article was last reviewed by our Support team on June 14, 2019.
