Encoding Webhooks

If you've built a video encoding pipeline, the default approach is to repeatedly ask Bitmovin 'is the encoding done yet?' — either manually or with a polling loop in your code. Webhooks are the better way.

What is a webhook?

A webhook is a way for one system to notify another when something happens, using a plain HTTP request. Instead of your application repeatedly checking Bitmovin for a status update, you give Bitmovin a URL on your server. When an encoding event occurs, Bitmovin sends an HTTP POST to that URL with details about what happened. Your server receives it, responds with 200 OK to acknowledge receipt, and reacts accordingly. Think of it like the difference between checking your mailbox every five minutes versus having the postal service ring your doorbell when a package arrives.

Why use webhooks over polling?

1. Efficiency. Polling burns API quota and server resources checking for a status change that may be minutes away. A webhook delivers the update the instant it happens — no wasted requests in between.
2. Simplicity. Your code doesn't need to manage timers, retry loops, or state machines. You register once and react when called.
3. Reliability at scale. If you're running dozens or hundreds of encoding jobs simultaneously, polling every one of them becomes a coordination problem. Webhooks scale horizontally — each job notifies you independently.
4. Real-time UX. With polling, you're always slightly behind. With webhooks, the user's interface updates the moment their video is ready.

Bitmovin's webhook events

Bitmovin supports several webhook types relevant to encoding workflows:

Each of these can be registered either globally (fires for all encoding jobs on your account) or per-encoding (fires only for a specific job). For most production setups, global webhooks are the right choice — register once, handle everything.

Creating a webhook in the Bitmovin Dashboard

If you prefer a UI over writing SDK code, you can create and manage webhook notifications directly in the Bitmovin Dashboard.

1. Navigate to VOD Encoding (or Live) → Configurations → Notifications → Webhook tab.
2. Click + Create.
3. Fill in the form:
   • Resource Type — e.g. Encoding
   • Event Type — e.g. Finished or Error
   • Target — set to Global to receive notifications for all encoding jobs on your account
   • Method — POST
   • URL — your callback endpoint
   • Allow Insecure SSL — leave as no unless your endpoint uses a self-signed certificate
4. Save the notification. It will appear in the list with a status of active.

From the same page you can view all existing webhooks, see their current status (active or muted), delete them, or create new ones.

Registering a webhook

Using the Bitmovin Typescript SDK

await bitmovinApi.notifications.webhooks.encoding.encodings.finished.create({
  url: webhookUrl,
  method: WebhookHttpMethod.POST,
});

await bitmovinApi.notifications.webhooks.encoding.encodings.error.create({
  url: webhookUrl,
  method: WebhookHttpMethod.POST,
});

await bitmovinApi.notifications.webhooks.encoding.encodings.transferError.create({
  url: webhookUrl,
  method: WebhookHttpMethod.POST,
});

📘

Note

Dashboard-created webhooks behave identically to those created via the SDK or API — there's no difference in delivery, payload, or retry logic.

Testing webhooks with a request inspection tool

Before wiring a webhook up to your production system, verify that Bitmovin is sending the correct events with the expected payloads. Several free tools provide a temporary public URL that captures incoming requests and displays the full headers and body in your browser—no server setup required.

Some popular options include:

• Webhook.site
• RequestBin
• Beeceptor

Step 1: Get a temporary URL

Sign up or navigate to one of the tools above. You'll be given a unique
public URL. Copy it and keep the tab open.

Step 2: Create the webhook in the Bitmovin Dashboard

1. Navigate to VOD Encoding (or Live) → Configurations →
   Notifications → Webhook tab.
2. Click + Create.
3. Fill in the form:
   • Event Type — select Finished for a basic test.
   • HTTP Method — select POST.
   • URL — paste your temporary URL here.
4. Click Save.

Step 3: Trigger an encoding and inspect the payload

Run any encoding job. When it completes, switch back to your inspection
tool — you'll see the full POST request Bitmovin sent, including the JSON
body with fields like the encoding ID, status, and timestamps.

This is useful for answering questions like:

• Is my webhook being called at all?
• What does the payload actually look like?
• Is the event firing at the right point in the encoding lifecycle?

Once you've confirmed everything looks right, swap the temporary URL for
your real endpoint.

📘

Note

These temporary URLs are public — don't use them in production or send
sensitive data through them. They're for development and debugging only.

Auto-mute

If your webhook endpoint becomes unreachable or stops returning 200 OK, Bitmovin will retry delivery up to 10 times. After 10 consecutive failures, the webhook is automatically muted and Bitmovin will stop attempting to deliver events — even after your server comes back online. You can learn more about how muting works and how to unmute a webhook here: Muting and Unmuting Webhooks