Webhooks

receive webhook notifications about video status

Webhooks allow you to receive real-time notifications when certain events occur. You can create, edit, and delete webhooks through our user interface (UI). This guide will walk you through each of these processes.

Creating a Webhook

  1. Navigate to the Webhooks Section

    • Click on the profile icon in the top right corner of the dashboard.

    • Select "Profile Settings" from the dropdown menu.

    • Scroll down to the "Account" section in the Profile Settings.

    • Click on the "Webhooks" tab.

Create a New Webhook

  • Click on the "Create Webhook" button.

  • Fill in the required fields:

    • Name: Give your webhook a descriptive name.

    • Description: Enter a Description

    • URL: Enter the URL where you want to receive the webhook notifications.

    • Events: Select the events that will trigger the webhook.

  • Click "Save" to create the webhook.

  • a webhook secret will automatically be generated

Editing a Webhook

  1. Navigate to the Webhooks Section

    • Go to the dashboard and click on the "Webhooks" tab in the sidebar.

  2. Select the Webhook to Edit

    • Find the webhook you want to edit from the list and click it.

  3. Edit the Webhook

    • Update the necessary fields (Name, URL, Events).

    • Click "Save" to apply the changes.

Endpoint Status Options

  1. Active:

    • Description: The endpoint is functioning normally and responding to events.

    • Effect: Events are sent to the endpoint as usual.

  2. Inactive:

    • Description: The endpoint has consecutively failed to process events.

    • Effect: New events are discarded and not sent.

    • Reactivation: Retry failed or discarded event delivery. If successful, the endpoint returns to Active. Batch retry all previously failed events to resume normal operation.

  3. Paused:

    • Description: The endpoint has been manually disabled to stop receiving events.

    • Effect: New events are discarded and not sent.

    • Reactivation: Un-pause the endpoint to set it back to Active.

  4. Pending:

    • Description: The endpoint was previously Inactive, and an event delivery is being resent.

    • Effect: If the resent event is successfully processed, the endpoint returns to Active.

Additional Options for Managing Webhooks

Beyond creating and editing webhooks, you have several management options to ensure that your webhooks operate effectively and securely. These options include pausing or un-pausing a webhook, deleting it, and regenerating its secret. You can access all these options from a dropdown menu by clicking on the three dots icon next to each webhook.

Best Practices

  • Use Secure URLs: Always use HTTPS URLs for webhooks to ensure data is transmitted securely.

  • Validate Webhook Signatures: If using secrets, validate the webhook signatures on your server to ensure the payload is from a trusted source.

Webhooks Payloads

Webhook Response Model

The following is the model of the data received from a webhook. This model specifies the structure of the response payload when a webhook event is triggered.

WebHookEvent

This is the main model representing a webhook event.

{
    "event_name": "video_ready",
    "data": {
        "id": "12345",
        "req_id": "abcde",
        "draft_id": "67890",
        "status": "ready"
    }
}

Fields:

  • event_name: Specifies the type of event that has occurred. For example, video_ready indicates that a video is ready.

  • data: Contains detailed information about the event.:

    • id: The unique identifier for the video.

    • req_id: The request ID associated with the video processing.

    • draft_id: The draft ID related to the video, if applicable.

    • status: The current status of the video, e.g., ready, indicating the video is ready.

Webhook Signature

To ensure the authenticity and integrity of webhook requests, a signature is included in the header of every request. This signature allows you to verify that the request was indeed sent by our service and has not been tampered with.

Signature Header

The signature is sent in the HTTP header of each webhook request. The header key is typically named x-hourone-signature, and its value is a hashed string that is used to validate the request.

Example Header:

x-hourone-signature: 3402330cf0c3ac7a4eceb7e979cde9cbd83cadfe84c63e4c6a51d9158491fee9

How to Verify the Signature

  1. Extract the Signature: Retrieve the signature value from the x-hourone-signature header.

  2. Calculate the Hash: Use the secret key provided when setting up the webhook to calculate the hash of the request payload. The hashing algorithm used should be the same as that employed by our service (HMAC-SHA256).

  3. Compare the Hashes: Compare the hash you calculated with the signature provided in the header. If they match, the request is authentic. If not, the request may be fraudulent or tampered with.

Example Code for Verification

Here's a Python example using HMAC-SHA256:

import hmac
import hashlib

def verify_signature(secret, payload, signature):
    computed_signature = hmac.new(
        key=secret.encode(),
        msg=payload.encode(),
        digestmod=hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(computed_signature, signature)

# Example usage
secret = 'your_secret_key'
payload = '{"event_name": "video_ready", "data": {"id": "12345", "req_id": "abcde", "draft_id": "67890", "status": "ready"}}'
received_signature = '3402330cf0c3ac7a4eceb7e979cde9cbd83cadfe84c63e4c6a51d9158491fee9'

if verify_signature(secret, payload, received_signature):
    print("Signature is valid.")
else:
    print("Signature is invalid.")

Example in Javascript (Node JS)

const crypto = require('crypto');

/**
 * Verify the signature of a webhook request
 * @param {string} secret - The secret key used to compute the hash
 * @param {string} payload - The payload received in the webhook request
 * @param {string} signature - The signature provided in the request header
 * @returns {boolean} - Returns true if the signature is valid, false otherwise
 */
function verifySignature(secret, payload, signature) {
    // Compute the HMAC-SHA256 hash of the payload using the secret key
    const computedSignature = crypto.createHmac('sha256', secret)
                                    .update(payload)
                                    .digest('hex');

    // Use the compare function to securely check if the computed signature matches the received signature
    return crypto.timingSafeEqual(Buffer.from(computedSignature), Buffer.from(signature));
}

// Example usage
const secret = 'your_secret_key';
const payload = JSON.stringify({
    event_name: 'video_ready',
    data: {
        id: '12345',
        req_id: 'abcde',
        draft_id: '67890',
        status: 'ready'
    }
});
const receivedSignature = '3402330cf0c3ac7a4eceb7e979cde9cbd83cadfe84c63e4c6a51d9158491fee9';

if (verifySignature(secret, payload, receivedSignature)) {
    console.log("Signature is valid.");
} else {
    console.log("Signature is invalid.");
}

Troubleshooting

  • Webhook Not Triggering: Ensure the URL is correct and the server is reachable.

  • Invalid Secret: If you're using a secret, make sure it matches the one expected by your server.

  • Event Not Selected: Double-check that the correct events are selected for the webhook.

PreviousSubtitlesNextVideo Status

Last updated