HTTP delivery

Ontoto can push data to an HTTP endpoint you host. Register the endpoint in the Ontoto Dashboard under Developer → Export Destinations → HTTP Endpoints, then attach it to an export. An endpoint has a URL, a method, static request headers such as an Authorization token, and an optional signing secret. Ontoto sends the payload as the raw body of a POST or PUT request. Exports send two kinds of payload:

File exports send the generated file as the body, with its path in X-Ontoto-File-Path.
Events send a small JSON body built by the export function, with no file. They suit a fetch-on-notify integration. For example, an export that runs when a device transmits tells your backend that new data has arrived, and your backend then fetches the readings through the sensor data API.

Signed requests follow the Standard Webhooks specification, so an off-the-shelf standard-webhooks library, available in most languages, can verify them for you.

Request headers

Every delivery carries these envelope headers:

Header	Description
`Content-Type`	Media type of the request body.
`webhook-id`	Unique id of the delivered payload. Every retry of the same payload, automatic or manual, carries the same id, so you can deduplicate.
`webhook-timestamp`	Unix timestamp (seconds) at which the request was sent. Included in the signature to bound replay attacks.
`webhook-signature`	Space-separated list of `<version>,<base64 signature>` entries, currently `v1,...`. Only present when a signing secret is configured.

Static headers configured on the endpoint, such as Authorization, go out unchanged on every request. File and event exports add their own headers on top of the envelope:

Header	Sent by	Description
`X-Ontoto-File-Path`	File exports	File path of the exported file body, defined on the export. Not included in event payloads.
`X-Ontoto-Export-Uuid`	Event exports	The applied export the event came from.
`X-Ontoto-Device-Sn`	Event exports	Serial number of the device the event covers. Absent when the export is not scoped to a device.
`X-Ontoto-Generated-At`	Event exports	ISO-8601 UTC instant the export ran, the same value the export function saw.

Ignore headers and webhook-signature versions you do not recognise. New export types and signature versions add entries without removing existing ones. The export generation history on the Exports page also logs each delivery’s webhook-id.

Verifying the signature

The signing secret shown when you configure the endpoint uses the Standard Webhooks whsec_<base64> format. The simplest check is a standard-webhooks library:

import { Webhook } from "standard-webhooks";

const wh = new Webhook("whsec_...");

// rawBody must be the unmodified request body; headers as received.
function handleDelivery(headers, rawBody) {
  wh.verify(rawBody, headers); // throws if invalid or outside the replay window
  // ... process the body
}

To verify manually instead:

Read webhook-timestamp and check it is within your replay window. The reference libraries default to 5 minutes either side of your server clock.
Base64-decode the secret after the whsec_ prefix. Those bytes are the HMAC key.
Compute the base64 HMAC-SHA256 over the UTF-8 bytes of {webhook-id}.{webhook-timestamp}.{raw body}. Use the raw body bytes exactly as received.
Compare the result against each v1,<signature> entry in webhook-signature with a constant-time comparison. Accept the request if any entry matches.

import { createHmac, timingSafeEqual } from "crypto";

// headers: lowercase-keyed, as Node delivers them. rawBody: a Buffer of the
// bytes as received, never a string or a parsed object.
function verifyOntotoSignature(headers, rawBody, secret) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;

  const ageMs = Math.abs(Date.now() - Number(timestamp) * 1000);
  if (Number.isNaN(ageMs) || ageMs > 5 * 60 * 1000) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key)
    .update(`${id}.${timestamp}.`)
    .update(rawBody)
    .digest("base64");

  return signatures.split(" ").some((entry) => {
    if (!entry.startsWith("v1,")) return false;
    const sig = Buffer.from(entry.slice("v1,".length));
    const exp = Buffer.from(expected);
    return sig.length === exp.length && timingSafeEqual(sig, exp);
  });
}

Why the replay window matters

The signature proves who sent a request and that nobody altered it. It does not prove when. Without a time check, a captured request would pass verification every time someone resent it. The timestamp is part of the signed content, so an attacker cannot change it without breaking the signature, and an old request replayed outside your window fails. Use webhook-id to deduplicate replays inside the window.

Test requests

The Send test request button in the endpoint dialog sends a small payload, by default the JSON body { "test": true }, through the same pipeline as a real delivery. The static headers, envelope headers and signature match a real delivery, so it tests connectivity, authentication and your signature check end to end.

Responding

Respond with any 2xx status to acknowledge a delivery. Any other status, or no response within 30 seconds, counts as a failed delivery.

Getting Started

Devices

Sensor Data

Device Groups

Sites

Outbound Delivery

Request headers

Verifying the signature

Why the replay window matters

Test requests

Responding

​Request headers

​Verifying the signature

​Why the replay window matters

​Test requests

​Responding

Request headers

Verifying the signature

Why the replay window matters

Test requests

Responding