Skip to content

Webhooks

HeapStream implements webhooks to inform your application about asynchronous events that occur outside the standard API request cycle. For instance, you might need to update your system when a video changes status from encoding to ready. In such scenarios, HeapStream will issue a POST request to your specified address, enabling you to process the information as required.

Once a webhook is set up for a project, it sends notifications for all related events. If your system fails to return a 2xx response to a webhook notification, HeapStream will retry sending the message over the next 24 hours, increasing the delay between each attempt.

While HeapStream strives to deliver each message once, there may be instances of duplicate webhook messages, even if your service acknowledges with a 2xx response. It's crucial to design your webhook handling system to accommodate potential duplicate deliveries effectively.

Webhooks Compared to Polling

We advise using webhooks for monitoring video statuses instead of polling the Video API. Webhooks are significantly more efficient for both your system and HeapStream. Additionally, we impose rate limits on GET requests to the /video endpoint, making polling an unscalable solution for tracking video status.

Configuring webhooks

You can configure webhooks in the project settings page.

Receiving events

HeapStream will initiate a POST request to a pre-set URL, a process your application can manage as it would any standard route. This allows your event handler to perform actions such as updating the status of a given video in your database or initiating additional tasks.

Be aware that each request attempt has a timeout limit of 5 seconds. If this period elapses without success, the attempt is marked as a failure and will be retried. If your workflow might be hindered by this constraint, consider handling the task asynchronously. This approach enables immediate response to the event.

For a comprehensive understanding of the Webhook event object and its structure, please refer to the provided example response.

Example response

Below is an example of an event:

{
  "event_type": "video.created",
  "project_id": 20,
  "timestamp": "2024-10-10T10:10:10.000010+0000",
  "video": {
    "asset": {
      "duration": -1.0,
      "encoding_tier": "full",
      "errors": [],
      "id": 22,
      "normalize_audio": false
    },
    "id": 500,
    "status": "waiting_for_upload"
  }
}

Types of events

Type of events: