Test Mux webhooks locally

Receive Mux events on your laptop while you build, with a URL Mux can reach.

Before you beginCopy Anchor Link

• Node.js 18 or later
• A Horizon account and the CLI (see Getting started)
• A reserved subdomain for -s. Reserve one on the Subdomains page.
• A Next.js app that uses the App Router and runs on port 3000
• A Mux account

npm install @mux/ts

import Mux from "@mux/ts";

const mux = new Mux({
  webhookSecret: process.env.MUX_WEBHOOK_SECRET,
});

export async function POST(request: Request) {
  const body = await request.text();

  let event: Awaited<ReturnType<typeof mux.webhooks.unwrap>>;
  try {
    event = await mux.webhooks.unwrap(body, request.headers);
  } catch (error) {
    const message = error instanceof Error ? error.message : "Unknown error";
    console.log(`Mux signature verification failed: ${message}`);
    return new Response("Invalid signature", { status: 400 });
  }

  console.log(`Received Mux event: ${event.type}`);

  return new Response("ok", { status: 200 });
}

MUX_WEBHOOK_SECRET=replace-with-your-signing-secret

npm run dev

hrzn tunnel http://localhost:3000 -s my-app

HORIZON: Tunnel connected
  URL          https://my-app.hrzn.run (reserved)
  Forwarding   http://localhost:3000
  Request log  https://hrzn.run/dashboard/tunnels/my-app

mux webhooks trigger video.asset.ready --forward-to http://localhost:3000/api/webhooks/mux

mux webhooks events list
mux webhooks events replay <event-id> --forward-to http://localhost:3000/api/webhooks/mux

Check it worksCopy Anchor Link

Create an asset in the environment you registered the webhook for. When it finishes processing, Mux sends video.asset.ready to your Horizon URL. Your Horizon terminal prints one line per event:

  POST    200  /api/webhooks/mux

Your app terminal prints:

Received Mux event: video.asset.ready

If the line shows [400], see Troubleshooting.

TroubleshootingCopy Anchor Link

The signature doesn't matchCopy Anchor Link

• Check that MUX_WEBHOOK_SECRET is the signing secret of the endpoint you registered. Each endpoint has its own.
• Pass unwrap the raw body from request.text(). Don't run JSON.parse and JSON.stringify first, because that can change the bytes.
• Restart npm run dev after you edit .env.local.
• The Mux CLI signs with a different secret. Events from mux webhooks trigger fail against your Dashboard endpoint's secret. Set MUX_WEBHOOK_SECRET to the secret that mux webhooks listen --forward-to prints when you test with the CLI.

Verification fails on an old eventCopy Anchor Link

Mux's SDKs allow 5 minutes between the timestamp in the header and the current time by default. A stored event that you send again later can fall outside it.

The request returns 404Copy Anchor Link

The Horizon line shows [404]. The webhook URL doesn't match your route. The file app/api/webhooks/mux/route.ts serves /api/webhooks/mux, and Mux sends POST requests.

The URL changed after a restartCopy Anchor Link

You started the tunnel without -s, so Horizon gave you a new random subdomain. Restart with -s my-app and the URL stays the same. -s needs a subdomain you reserved, see Pricing.

Nothing reaches your appCopy Anchor Link

• Check that the Horizon terminal is still running. If its last line is Connection lost. Reconnecting…, wait for Reconnected.
• Check that the webhook is registered for the environment where the event happens.

Next stepsCopy Anchor Link

• Read Mux's guide to verifying webhook signatures.
• See the full list of events in Listen for webhooks.