Webhooks

A webhook makes Wexa send a signed JSON POST to a URL you choose each time an ontology in your project is committed, updated or discarded.

Anyone who can reach the project's ontology management in the console can create one; the handler checks no role of its own, and which roles reach it is not stated in source. You manage webhooks in the console; no SDK method or public API route wraps them today.

Delivery contract

Wexa does not wait for your answer before carrying on. Delivery runs in the background after the change is saved, so a slow or failing receiver never blocks the edit that triggered it.

Create a webhook in the console

1. In the console sidebar, open Connectors and choose the Ontology tab at the top of the page.
2. In the ontology management bar, choose the Webhooks tab, then select Add Webhook.
3. Optionally enter a Name; it defaults to Webhook.
4. Enter the destination URL, for example https://example.com/hooks/fabric. It is required for every event except Inbound.
5. Tick the events you want: Committed, Updated or Discarded. Committed is ticked by default. The Inbound option makes the webhook an ingest endpoint instead; that endpoint is not on the public gateway, so this page does not cover it.
6. Leave Rate limit (per min) at its default of 60 unless you need otherwise. It applies only to inbound requests; deliveries to your URL are not throttled.
7. Save. A green banner shows the secret, once. Copy it now: afterwards the row shows only its last four characters, as secret_hint.

Each webhook is a row in the Webhooks tab with an active or paused pill. Pause stops deliveries, Resume restarts them, and the bin icon deletes the webhook. Expand a row to see Recent deliveries: the event, status code, duration, any error and the time of each attempt.

Payloads

Every delivery has the same envelope. Keys arrive in alphabetical order, because the body is serialised from a map:

ontology.committed

Sent the first time a proposal is committed as an ontology.

{"data":{"nodes":12,"ontology_id":"ont_customers","proposal_id":"6650a1f2c3d4e5f607182930","proposal_name":"Customers","recommit":false,"relationships":9},"event":"ontology.committed","project_id":"proj_example","timestamp":"2026-11-03T09:30:00Z"}

ontology.updated

Sent from four places, and the data fields depend on which:

{"data":{"ontology_id":"ont_customers","ontology_name":"Customers","scope":"project"},"event":"ontology.updated","project_id":"proj_example","timestamp":"2026-11-03T09:41:07Z"}

ontology.discarded

Sent when an ontology is deleted from the graph.

ontology.inbound

Never delivered to you. Choosing it turns the webhook into an ingest endpoint instead, which this page does not cover.

Verify a delivery

Wexa signs the exact bytes of the request body with HMAC-SHA256, keyed with your webhook's secret, and sends the result as:

X-Signature-SHA256: sha256=<64 hex characters>

The key is the secret string as shown, all 64 characters used as text, not decoded from hex. Compute the digest over the raw body before you parse it: re-serialising JSON changes the bytes, and Wexa's serialiser escapes <, > and &.

The signature carries no timestamp and Wexa states no tolerance window. The timestamp field is inside the signed body, so it cannot be altered without breaking the signature; whether to reject old ones, and how old, is your policy. Wexa also sends no delivery id, so you cannot de-duplicate on one.

Test vector. With secret 9f2c41d7b8a35e60c1d4f7a92b3e8c05a6d1f4e7b2c93a58d0e6f1b7c4a29d83 and the ontology.committed body above, the header is sha256=26672933a945a5ba051f27f73b07bef24353785811b1922866a6b95c10f36779.

# BODY is the request body exactly as received; SECRET is the webhook secret.
printf %s "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/.*= /sha256=/'
# Compare the output with the X-Signature-SHA256 header.

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

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

import hashlib
import hmac


def verify(raw_body: bytes, secret: str, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

Respond with any status below 300 once the signature checks out, and answer a bad signature with 401; Wexa only records the code.

Retries

Wexa does not retry. Each event is delivered once, and a failure is written to the webhook's delivery log (status code, duration and error) and nothing else; there is no schedule, no backoff and no dead-letter queue. The log keeps the latest 500 deliveries per webhook. If your receiver was down, read the log, then re-read the ontology; events are not replayed.

Limits and behavior