Developers / Webhooks

Generic signed webhooks (platform feature).

A generic, platform-level outbound webhooks feature: subscribe to event types and receive HMAC-SHA256-signed POST deliveries. Level Zero products and corroboration candidates are not yet wired to emit webhooks.

TransportHTTPS POST, JSON SigningHMAC-SHA256 in Webhook-Signature header ScopePlatform-generic; not wired to Level Zero events

Event types

Webhooks are a generic platform module: you subscribe by event type and a worker delivers a signed POST. The events below are illustrative of the platform model; Level Zero ingest, product and corroboration events are not yet wired to webhook delivery.

EventFires when…
ingest.acceptedAn input has been validated and scheduled for processing.
ingest.rejectedAn input failed validation. Reason in data.error.
job.startedA pipeline job has started execution.
job.succeededA job completed and a receipt was issued.
job.failedA job failed. Final state is captured with engine version and parameters.
record.conditionedA telemetry frame was stored as hex, frame-byte counted and normalised into a canonical product (roadmap; not yet wired).
corroboration.candidateA bounded corroboration candidate was produced (75 km / 30 min gate, ≥2 source types) - roadmap; not yet wired.
product.publishedA canonical product (schema lz.canonical.v1) was signed and chained - roadmap; not yet wired.

Delivery

POST /your/webhook HTTP/1.1
Content-Type: application/json
Webhook-Id: evt_01H9X…
Webhook-Timestamp: 1748462953
Webhook-Signature: v1,t=1748462953,sig=…

{
  "type": "product.published",
  "id": "evt_01H9X…",
  "created": "2026-05-29T01:09:13Z",
  "data": {
    "recordHash": "…",
    "href": "https://api.levelzero.fr/api/level-zero/products/..."
  }
}

Signature

Each delivery is signed with HMAC-SHA256 over timestamp + "." + body using your endpoint secret. Verify the signature and the timestamp (≤ 5 minutes drift) before trusting the payload.

// Node
import { createHmac, timingSafeEqual } from "node:crypto";
const sig = createHmac("sha256", secret).update(`${ts}.${body}`).digest("hex");
const ok  = timingSafeEqual(Buffer.from(sig), Buffer.from(received));

Replay

The webhooks module records delivery attempts so you can inspect their status. A windowed replay API and a fixed retention window are roadmap, not yet implemented.

Manage endpoints

Create endpoints, set a signing secret and subscribe by event type via the webhooks module API. Scoping to Level Zero Collections does not apply - there are no STAC Collections, and Level Zero events are not yet wired to webhooks.

[ Ready to integrate ]