Test Frame.io webhooks locally

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

This guide covers Frame.io V4 webhooks. You create them with the V4 API.

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 Frame.io V4 account, with its account ID and workspace ID
• An OAuth 2.0 access token from the Adobe Developer Console. The V4 API doesn't accept legacy developer tokens or JWTs.

import { createHmac, timingSafeEqual } from "node:crypto";

const MAX_TIMESTAMP_AGE_SECONDS = 5 * 60;

export async function POST(request: Request) {
  const signingSecret = process.env.FRAMEIO_SIGNING_SECRET;
  if (!signingSecret) {
    return new Response("Missing FRAMEIO_SIGNING_SECRET", { status: 500 });
  }

  const body = await request.text();
  const timestamp = request.headers.get("x-frameio-request-timestamp") ?? "";
  const received = request.headers.get("x-frameio-signature") ?? "";

  const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!(ageSeconds < MAX_TIMESTAMP_AGE_SECONDS)) {
    return new Response("Stale timestamp", { status: 401 });
  }

  const digest = createHmac("sha256", signingSecret).update(`v0:${timestamp}:${body}`).digest("hex");
  const receivedBuffer = Buffer.from(received);
  const expectedBuffer = Buffer.from(`v0=${digest}`);
  const isValid =
    receivedBuffer.length === expectedBuffer.length &&
    timingSafeEqual(receivedBuffer, expectedBuffer);

  if (!isValid) {
    return new Response("Invalid signature", { status: 401 });
  }

  const event = JSON.parse(body) as { type: string; resource: { id: string; type: string } };
  console.log(`Received Frame.io event: ${event.type} ${event.resource.id}`);

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

FRAMEIO_SIGNING_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

curl -X POST "https://api.frame.io/v4/accounts/$FRAMEIO_ACCOUNT_ID/workspaces/$FRAMEIO_WORKSPACE_ID/webhooks" \
  -H "Authorization: Bearer $FRAMEIO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "Horizon test",
      "url": "https://my-app.hrzn.run/api/webhooks/frameio",
      "events": ["file.created"]
    }
  }'

Check it worksCopy Anchor Link

Upload a file to a project in the workspace. Your Horizon terminal prints one line:

  POST    200  /api/webhooks/frameio

Your app terminal prints:

Received Frame.io event: file.created <file id>

A file.created event can arrive before the upload finishes. Use file.upload.completed or file.ready when you need the finished file.

If the line shows [401], see Troubleshooting.

TroubleshootingCopy Anchor Link

The signature doesn't matchCopy Anchor Link

• Check that FRAMEIO_SIGNING_SECRET is the secret from the create response of this webhook.
• Build the message as v0:<timestamp>:<body>, with the raw body.
• Prefix your computed digest with v0= before you compare.
• Restart npm run dev after you edit .env.local.

You lost the signing secretCopy Anchor Link

Frame.io returns the secret only in the create response. Delete the webhook with DELETE /v4/webhooks/{webhook_id} and create a new one.

The webhook is inactiveCopy Anchor Link

Webhooks migrated from Frame.io Legacy are disabled when your account moves to V4. Check is_active on the webhook, or update it with PATCH /v4/webhooks/{webhook_id}.

The request returns 404Copy Anchor Link

The Horizon line shows [404]. The webhook URL doesn't match your route. The file app/api/webhooks/frameio/route.ts serves /api/webhooks/frameio, and Frame.io 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. Update the webhook with PATCH /v4/webhooks/{webhook_id} and the new url, or 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 action happened in a project of the workspace you registered the webhook for, and that the event type is in the webhook's events.

Next stepsCopy Anchor Link

• Read Frame.io's V4 webhooks guide.