Webhook payloads

Every subscription receives a POST to your target URL with headersX-MatterMesh-EventandX-MatterMesh-Signature(an HMAC-SHA256 of the raw JSON body using your subscription's signing secret, prefixed with sha256=). Verify the signature before trusting the payload.

Common envelope

Every payload is shaped like this. Only the eventand data fields differ per event.

{
  "event":       "walkaround.ready",
  "scan_id":     "uuid",
  "occurred_at": "ISO-8601 timestamp",
  "data":        { /* event-specific */ }
}

Events

scan.processed

Once, when the scan transitions to processed.

A scan finished its main processing pipeline successfully.

{
  "event": "scan.processed",
  "scan_id": "1e6c…",
  "occurred_at": "2026-07-15T14:00:00.000Z",
  "data": {
    "duration_ms": 12480
  }
}

scan.published

After scan.processed once the scan is visible on the site.

A scan is publicly listed and its assets are downloadable.

{
  "event": "scan.published",
  "scan_id": "1e6c…",
  "occurred_at": "2026-07-15T14:00:00.000Z",
  "data": {}
}

scan.failed

Once per failed run. Retries emit a new event on the next failure.

A scan halted with an unrecoverable error.

{
  "event": "scan.failed",
  "scan_id": "1e6c…",
  "occurred_at": "2026-07-15T14:00:00.000Z",
  "data": {
    "error": "frame_extraction_failed"
  }
}

walkaround.started

Once, at 0% → first tick.

The walkaround matting pipeline began for a scan.

{
  "event": "walkaround.started",
  "scan_id": "1e6c…",
  "occurred_at": "2026-07-15T14:00:00.000Z",
  "data": {
    "stage": "queued",
    "progress": 25
  }
}

walkaround.progress

On every stage transition below ready.

The walkaround pipeline advanced to a new stage.

{
  "event": "walkaround.progress",
  "scan_id": "1e6c…",
  "occurred_at": "2026-07-15T14:00:00.000Z",
  "data": {
    "stage": "matting",
    "progress": 55
  }
}

walkaround.ready

Once per matte version.

The walkaround matted video / mesh is ready. Includes the matte version number, which bumps every time we re-mint the archival output.

{
  "event": "walkaround.ready",
  "scan_id": "1e6c…",
  "occurred_at": "2026-07-15T14:00:00.000Z",
  "data": {
    "stage": "ready",
    "progress": 100,
    "matte_version": 3
  }
}

walkaround.failed

Once per failure or user cancel.

The walkaround pipeline failed or was canceled.

{
  "event": "walkaround.failed",
  "scan_id": "1e6c…",
  "occurred_at": "2026-07-15T14:00:00.000Z",
  "data": {
    "error": "canceled",
    "stage": "canceled"
  }
}

scan.indexed

On each successful (re)index.

MatterMesh confirmed a search / LLM crawler indexed this scan.

{
  "event": "scan.indexed",
  "scan_id": "1e6c…",
  "occurred_at": "2026-07-15T14:00:00.000Z",
  "data": {
    "crawler": "GPTBot"
  }
}

Signature verification (Node)

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

function verify(body: string, signature: string, secret: string) {
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && timingSafeEqual(a, b);
}