Webhooks

Perculus Webhook System

Introduction

Perculus uses webhooks to notify external systems about particular events. To use this functionality, a webhook should be registered to store information, including the webhook endpoint URL (a.k.a listener URL) and the event type. When an event associated with a webhook happens, an HTTP POST payload is sent to the associated URL. Please contact the support team if you want to use this feature and register your webhook URL.

Events and Messages

The following is the list of Perculus events and corresponding messages to notify the associated webhooks.

SessionReportEvent

This event is dispatched after a session is packed and report data are available. The status can be ready or failed. If an error occurred during the preparation of the report, an error text is also included in the message.

SessionReportEvent Message (Successful Operation)

{ 
    "request_id": "bd943129-f2eb-4b52-9bf9-784c87d1b80e",
    "type": "SessionReportEvent",
    "session_id": "805368AF-B096-42D4-8233-1B0C0EBF1DB2",
    "token": "63833938902|Uu4T7EFsl6dfBfLjFbVKizWerUJ4q9/pA9UokdW+Vv0=",
    "status": "ready"     
} 

SessionReportEvent Message (Failed Operation)

{
    "request_id": "bd943129-f2eb-4b52-9bf9-784c87d1b80e",
    "type": "SessionReportEvent",
    "session_id": "805368AF-B096-42D4-8233-1B0C0EBF1DB2",
    "token": "63833938902|Uu4T7EFsl6dfBfLjFbVKizWerUJ4q9/pA9UokdW+Vv0=",     
    "status": "failed",
    "error": "error text comes here" 
} 

SingleVideoEvent

This event is dispatched after the video file is ready to be downloaded. If the status is failed, an error text is also included in the message.

SingleVideoEvent Message (Successful Operation)

{ 
    "request_id": "0489b550-df7f-4807-a693-22fcd6c9ccf5", 
    "type": "SingleVideoEvent",
    "session_id": "AF7F81CA-167B-43C0-94F7-E6835B30B043",
    "token": "63833938902|Uu4T7EFsl6dfBfLjFbVKizWerUJ4q9/pA9UokdW+Vv0=",
    "status": "ready",
    "video_url": "https://storage-system.perculus.com/files/0f19be98e5442ec8f9439c7435f5a7f.mp4?token=xhiUZSLoFe4y9VLCYz17TZiKcZk%3D" 
} 

SingleVideoEvent Message (Failed Operation)

{
    "request_id": "bd943129-f2eb-4b52-9bf9-784c87d1b80e",
    "type": "SingleVideoEvent",
    "session_id": "AF7F81CA-167B-43C0-94F7-E6835B30B043",
    "token": "63833938902|Uu4T7EFsl6dfBfLjFbVKizWerUJ4q9/pA9UokdW+Vv0=",
    "status": "failed",
    "error": "error text comes here" 
} 

SessionStatusEvent

This event is dispatched after a session is started or finished.

The event data is encapsulated as a JSON payload and included in an HTTP POST request to the webhook endpoint URL.

SessionStatusEvent Message

{ 
    "request_id": "bd943129-f2eb-4b52-9bf9-784c87d1b80e",
    "type": "SessionStatusEvent",
    "session_id": "805368AF-B096-42D4-8233-1B0C0EBF1DB2",
    "token": "63833938902|Uu4T7EFsl6dfBfLjFbVKizWerUJ4q9/pA9UokdW+Vv0=",
    "status": "started",
    "date": "2024-01-23T17:41:07"
} 

Message Fields

Name	Description	Types
request_id	This unique identifier identifies the message. It can be used to track messages and troubleshoot problems.	All
type	The type of the message.	All
session_id	This is the unique identifier of the Perculus session.	All
token	This is the authentication token used by the webhook endpoint to verify the Perculus platform. See "Token Generation and Verification".	All
status	This can have two values for SessionReportEvent and SingleVideoEvent messages, which are ready and failed. The status field in the SessionReportEvent payload indicates whether the session has been correctly packaged. Similarly, the status field in the SingleVideoEvent payload indicates whether the session video has been successfully created. If the status is failed, an error message is transmitted within the error element. It can take started or finished values for SessionStatusEvent.	All
video_url	This element specifies the URL where the video content is located. This URL can be utilized to access the video content and expires after 24 hours.	SingleVideoEvent
date	This element specifies when the session started or finished depending on the value of the status field.	SessionStatusEvent
error	This element contains the error text of the event in case of any errors. It’s an optional element which is omitted if there is no error.	SessionReportEvent SingleVideoEvent

Token Generation and Verification

The receiver system can authenticate the Perculus system by verifying the authentication token sent within the messages. As shown in the sections above, Perculus includes a token element in each webhook URL request payload. It is in the following format:

token = <timestamp>|<hmac>

The hmac is a hash-based message authentication code. It’s generated by using a secret and a timestamp.

The timestamp is the number of seconds passed from 1/1/1970 UTC to the token creation time. It is also known as the Unix time.

The secret is a private piece of information that is only known by the Perculus and the receiver side.

The pseudo-code of the token generation is as follows:

var token_content = utf8_bytes(timestamp);
var hmac_sha256_key = utf8_bytes(secret);
var hmac_sha256_generator = hmac_sha256(hmac_sha256_key);
var hmac = hmac_sha256_generator.compute_hash(token_content);
var token = timestamp + "|" + hmac;

Since the secret is also known by the receiver side, the receiver can re-generate the hmac by using the timestamp, which is embedded in the token and the secret by using the above algorithm. Thus, the receiver can verify:

• The validity of the request by checking that the token has not expired if the timestamp is at most N minutes old. Here, deciding the N parameter is up to the receiver side.

• The authenticity of the request (by checking whether the hmacs are equal). The following C# code snippet is a method that generates an authentication token using a secret and a timestamp, as explained above in the document.

Sample C# Code to Generate an Authentication Token

public static string CreateAuthToken(string secret, DateTime httpRequestUTCDate) { 
    if (String.IsNullOrEmpty(secret)) 
        throw new ArgumentException("secret cannot be empty"); 
    // Calculate Unix timestamp which is 
    // the total seconds passed since 1/1/1970 UTC 
    var timestamp = Math.Floor((httpRequestUTCDate - new DateTime(1970, DateTimeKind.Utc)).TotalSeconds).ToString(); 
    // Generate an hmac using HMAC-SHA256 algorithm 
    var keyBytes = System.Text.Encoding.UTF8.GetBytes(secret); 
    var hmacsha256 = new System.Security.Cryptography.HMACSHA256(keyBytes);
    var messageBytes = System.Text.Encoding.UTF8.GetBytes(timestamp);
    var hmac = Convert.ToBase64String(hmacsha256.ComputeHash(messageBytes));
    // Return the token, which combines unix timestamp and hmac 
    return timestamp + "|" + hmac; 
}