Skip to main content

Webhooks

Webhooks provide a powerful way to receive real-time notifications about events happening within the Cloud Video Kit platform. By subscribing to specific events, you can build integrations that react instantly, such as starting a post-processing workflow when a recording is finished or updating a live status indicator when a stream starts.

This guide covers the technical details you need to securely and reliably receive and process webhooks.

For instructions about configuring Webhooks in the Cloud Video Kit Console, see our User Guide article.

Understanding the Webhook Payload​

When an event you've subscribed to occurs, we'll send an HTTP POST request to your configured Target URL. The request body contains a JSON object with the event details.

A typical webhook payload looks like this:

{
  "id": "50cace1d-32a1-4e7b-a5fa-c1791c2da581",
  "time": "2025-09-18T07:11:20.8608167+00:00",
  "dataContentType": "application/json",
  "source": "/tenant/261da705-65ff-4978-b438-1fe14d96b09a",
  "specVersion": "1.0",
  "type": "webhook.test",
  "data": {
    "id": "09000000-d08c-2c90-4a15-08ddf68291ca"
  }
}
  • id: A unique identifier for this specific event instance. You can use this ID to de-duplicate events and prevent processing the same event multiple times, which is crucial for handling retries.
  • time: The timestamp for when the event was generated.
  • source: Identifies the ID of the tenant related to the event that occurred.
  • specVersion: A reference version number for debugging.
  • type: A string that identifies the type of event that occurred (for instance, webhook.test, cvr.recording.created).
  • data: This object contains the payload of the event message.
    • data.id: The object ID related to the webhook type notification. For example, for a vod.asset.updated webhook, it will be the ID of the asset.

Understanding the Request Headers​

Every webhook POST request includes the following HTTP headers:

POST /7488c72f-6cde-436f-9b21-71493be08cc6
X_REQUEST_ID: aa99625c44889d6adecc329712123c4c
X_CVK_SIGNATURE_V1: 728b7e30ca513dd3fe0934982f5a746f2b15b46991e2a5b7d2998b6d8d5dc733
  • X_REQUEST_ID: A unique identifier for the HTTP request, useful for logging and debugging.
  • X_CVK_SIGNATURE_V1: This is the most important header for security. It contains the HMAC SHA256 signature of the request payload, which you should verify to ensure the request is authentic.

Verifying Webhook Signatures​

To ensure that the requests sent to your endpoint are legitimate and originate from Cloud Video Kit, we sign every webhook request. Each request includes the signature in the X_CVK_SIGNATURE_V1 HTTP header, which is generated using the shared Secret key found in the Notifications tab of the console.

You should verify this signature before processing the payload. The verification process is as follows:

  1. Retrieve the webhook's Secret key from the console.
  2. Read the raw body of the incoming HTTP POST request.
  3. Compute an HMAC with the SHA256 hash function. Use the Secret key as the key and the raw request body as the message.
  4. Compare the hash you computed with the signature provided in the X_CVK_SIGNATURE_V1 header. If they match, the webhook is authentic.

Responding to Webhooks​

Your endpoint must acknowledge the receipt of a webhook promptly.

  • Successful Acknowledgment: To acknowledge that you've successfully received the webhook, your endpoint must return a 200 OK HTTP status code.
  • Response Time: You must send this response very quickly, preferably within one second.

Any response code other than 200 will be considered a failure. It's critical to perform any complex or long-running logic asynchronously after you've sent the 200 response. If your server takes too long to respond, the connection will time out, which will also be treated as a failure.

Handling Retries and Failures​

If we don't receive a 200 OK response within the time limit, the Cloud Video Kit server will consider the delivery to have failed and will retry sending the webhook. It will continue to retry sending the webhook for a certain period. If deliveries continue to fail, the server will stop sending requests, and the webhook's status in the console will change to "Unhealthy".

Because of this retry logic, your endpoint might receive the same event notification more than once. You should make your event processing idempotent by using the id to track events you've already processed.