Skip to content

Creating Subscriptions

Subscriptions are created with the wh sub create CLI command, the warmhub_subscription_create MCP tool, or the SDK client.subscription.create(...) method. Subscription management REST endpoints are not currently mounted.

Two pieces of a webhook subscription have their own pages: the Filter JSON that selects which writes fire it, and the credentials and signature verification for securing deliveries. This page covers creating webhook subscriptions; Advanced below covers cross-graph and self-chaining setups.

A webhook subscription sends an HTTP POST to your URL when matching operations or metadata events occur.

WarmHub supports thirteen event types for webhook subscriptions:

Event typeScopeDescription
commit (default)GraphFires when writes matching a filter land in the graph. Requires filterJson and webhook URL; most webhooks also bind to a target shape via --on <shape> (or shapeName in the SDK/MCP).
repo.renamedGraphFires when the graph itself is renamed. Rejects shapeName, filterJson, and sourceGraphRef.
thing.renamedGraphFires when a thing in the graph is renamed. Rejects shapeName, filterJson, and sourceGraphRef.
shape.renamedGraphFires when a shape in the graph is renamed. Rejects shapeName, filterJson, and sourceGraphRef.
org.renamedOrgFires when the org is renamed. Rejects shapeName, filterJson, sourceGraphRef, and graphName.
org.member_addedOrgFires when a member or pending invite is added. Rejects shapeName, filterJson, sourceGraphRef, and graphName.
org.repo_createdOrgFires when a private or public graph is created. Rejects shapeName, filterJson, sourceGraphRef, and graphName.
org.repo_publishedOrgFires when an existing private graph becomes public. Rejects shapeName, filterJson, sourceGraphRef, and graphName.
org.service_account_created, org.service_account_role_changed, org.service_account_disabled, org.service_account_enabled, org.service_account_deletedOrgFire when a service account is created, changes role, is disabled or enabled, or is deleted. Reject shapeName, filterJson, sourceGraphRef, and graphName.

For commit subscriptions, most webhooks bind to a target shape via --on <shape> (or shapeName in the SDK/MCP) — that scopes the subscription to things and assertions of that shape. The one exception is shape lifecycle subscriptions: they omit --on and rely on a {"kind":"shape"} filter to subscribe to shape adds, revises, retracts, and restores. See Filter JSON for the full filter grammar.

Metadata subscriptions (the *.renamed events and the org activity events such as org.member_added, org.repo_created, and org.repo_published) use an eventType instead of a filter. Graphs were formerly called repos, which is why repo.renamed and the org.repo_* event names still say repo. Org-scoped metadata subscriptions use orgName without graphName (the MCP tools additionally require scope: "org") and can be created only by organization owners and admins.

When you create a same-graph commit subscription using a token whose scope is limited by a grant, the shapes available to that subscription are limited to those inside the grant’s selection. A cross-graph subscription is different: its shape is looked up in the source graph, and the grant’s selection on the home graph does not limit it.

With a grant-limited token:

  • Shapes inside the grant’s selection — the subscription is created normally.
  • Shapes outside the grant’s selection, or shapes that are hidden from the caller — the request is rejected as if the shape does not exist. You will not receive a different error to distinguish “shape exists but you can’t subscribe to it” from “shape does not exist.”
  • Graph-scoped metadata event types (repo.renamed, thing.renamed, shape.renamed) — these require whole-graph read access. A grant-scoped caller who does not have whole-graph read will receive a validation error when attempting to create one of these subscriptions.

If a commit subscription on a shape you expect to exist is rejected unexpectedly, confirm that the token’s grant covers that shape before investigating further.

WarmHub validates webhook URLs at subscription create/update time and again at delivery time. URLs that don’t meet these requirements are rejected with the message “Webhook target is not reachable or not allowed”.

  • HTTPS required. Production WarmHub deployments do not deliver to http:// URLs.
  • Port allowlist: 80, 443, or 8443. Other ports (for example 25, 22, or 6379) are rejected.
  • Must resolve to a public IP address. WarmHub rejects loopback addresses like 127.0.0.1, private-network addresses (RFC 1918 ranges such as 10.0.0.0/8 and 192.168.0.0/16), link-local addresses, cloud-provider metadata IPs, and similar reserved ranges.
  • Encoded IP bypasses are rejected. WarmHub blocks non-canonical numeric host forms even when the scheme is otherwise allowed — examples include https://2130706433/ (decimal-encoded 127.0.0.1), hex or octal IP literals, IPv4-mapped IPv6 forms, and 6to4-mapped private IPs.
  • No credentials in the URL. https://user:pass@host/ is rejected. Use credential binding to attach auth headers instead.
  • Use a canonical hostname. WarmHub accepts normal DNS hostnames and canonical IP literals only.

The same rules apply to fallbackWebhookUrl — an optional secondary endpoint WarmHub calls after a terminal delivery failure on the primary webhook. Set it via the SDK fallbackWebhookUrl field (see client.subscription), the CLI --fallback-webhook-url flag, or the warmhub_subscription_create / warmhub_subscription_update MCP tools.

For local development, expose your receiver through a public HTTPS tunnel (for example ngrok or Cloudflare Tunnel) and point the subscription at the tunnel URL. WarmHub does not deliver to http:// URLs or to private/loopback IPs.

WarmHub re-validates every redirect hop against the same webhook URL rules above. A URL that passes create-time validation can still fail at delivery time if it redirects to:

  • a non-HTTPS target
  • a non-allowlisted port
  • a private, loopback, link-local, or otherwise reserved address
  • a non-canonical numeric host form

WarmHub also enforces a redirect-follow limit. If the target loops or exceeds that cap, the attempt fails with WEBHOOK_REDIRECT_LIMIT.

If a redirect crosses origins, WarmHub does not forward your auth, signature, idempotency, run-tracing, or W3C trace-propagation headers to the new origin. Only body-describing headers needed to preserve the request payload are retained. In practice, that means webhook endpoints behind a vanity redirector or cross-origin bounce URL should terminate on the final receiving origin directly rather than relying on WarmHub to carry credentials across origins.

If validation fails, the outcome falls into one of two buckets:

  • Your URL is rejected. The request comes back with the message Webhook target is not reachable or not allowed. Edit the URL to match the rules above before retrying — the same message is used for every reason (scheme, port, host form, credentials, reserved IP, …) on purpose, so the surface can’t be used to fingerprint internal infrastructure.
  • WarmHub couldn’t check it right now. The request comes back with the message Webhook URL validation temporarily unavailable, please retry. This means a transient infrastructure issue (typically a DNS resolver hiccup) interrupted the check before validation could finish. Submit the same request again once the resolver issue clears.
Terminal window
# Default commit subscription
wh sub create sensor-hook \
--on Sensor \
--kind webhook \
--filter '{"shape":"Sensor"}' \
--webhook-url https://example.com/hook
# Graph rename subscription
wh sub create graph-rename-hook \
--kind webhook \
--event repo.renamed \
--webhook-url https://example.com/hook
# Org rename subscription
wh sub create org-rename-hook \
--org myorg \
--kind webhook \
--event org.renamed \
--webhook-url https://example.com/hook
# Optional: allow same-trace reentry for a self-chaining webhook
wh sub create sensor-loop \
--on Sensor \
--kind webhook \
--filter '{"shape":"Sensor"}' \
--webhook-url https://example.com/hook \
--allow-trace-reentry

warmhub_subscription_create creates subscriptions in either scope, selected by the scope argument. Graph-scoped event types (commit, repo.renamed, thing.renamed, shape.renamed) are the default and require graphName. Org-scoped event types (org.renamed, org.member_added, org.repo_created, org.repo_published, and the five org.service_account_* events) need scope: "org".

{
"name": "warmhub_subscription_create",
"arguments": {
"orgName": "myorg",
"graphName": "mygraph",
"name": "sensor-hook",
"kind": "webhook",
"shapeName": "Sensor",
"filterJson": { "shape": "Sensor" },
"webhookUrl": "https://example.com/hook"
}
}

For graph-scoped metadata event types (repo.renamed, thing.renamed, shape.renamed), omit shapeName, filterJson, and sourceGraphRef from the warmhub_subscription_create arguments.

For org-scoped event types, pass scope: "org" and omit graphName, shapeName, filterJson, and sourceGraphRef. An omitted eventType then means org.renamed. Omitting graphName without scope: "org" is an error, not a silent switch to org scope.

The POST body shape depends on the subscription’s event type. Use the event field to branch handler logic.

Note that the event field in the delivered payload is not the same as the create-time event type selector. For example, a subscription created with event type commit delivers payloads whose event field is "warmhub.write" or "warmhub.retract" — not "commit".

FieldDescription
event"warmhub.write" or "warmhub.retract"
traceIdUnique trace identifier for the event chain
runIdAction run identifier
subscriptionNameName of the subscription that fired
callback_urlCallback endpoint to report asynchronous progress or terminal outcome for this run
graph{ "orgName", "graphName" } — the subscription’s home graph
graphSeqThe write sequence number of the write that produced this event, counted within the graph that made the write. For a same-graph subscription this is the home graph; for a cross-graph subscription it is the source graph, which may differ from the graph in the graph field. Use graphSeq to order deliveries from a single subscription; do not pair it with graph to look up a write when the subscription is cross-graph. Absent on events with no write behind them.
matchedOperationIndexesIndexes of operations that matched the filter
matchedOperationsThe matched operations. See the field details below.

matchedOperations field details

Each entry in matchedOperations is a wrapper object with two fields:

FieldTypeDescription
indexnumberPosition of this operation in the original write
operationobjectThe operation details — see the sub-fields below

The operation details live inside the nested operation object:

FieldDescription
operationThe operation verb (for example "add", "revise", "retract", "rewrite"); use this to distinguish the kind of change
nameThe thing’s short name as stored (for example cave or acme), or hub/shapes/<Name> for a shape operation
declaredShapesPinned shape wrefs for this operation. Same-graph shapes appear as bare names such as Deal@v1; shapes defined in another graph appear as fully qualified wrefs such as wh:org/graph/Deal@v1. Always present, but may be an empty array (see edge cases below).
validatedShapesPinned shape wrefs for this operation, using the same format as declaredShapes — bare names for same-graph shapes, canonical wrefs for foreign shapes. Always present, but may be an empty array (see edge cases below).
dataPresent when the operation carries a data payload
durableIdThe stable, rename-safe identifier for the thing or shape

To illustrate the nesting, a single entry looks like this:

{
"index": 0,
"operation": {
"operation": "add",
"name": "cave",
"declaredShapes": ["Deal@v1"],
"validatedShapes": ["Deal@v1"],
"data": { "temperature": 22.5 },
"durableId": "040SXA5RYM7Q4QXAGM8N6MXYVH5G37TDS2P16YQAG6D6M3VKT6YE8ZCW52H0"
}
}

When a thing’s shapes come from a different graph, the wrefs are fully qualified:

{
"index": 0,
"operation": {
"operation": "add",
"name": "cave",
"declaredShapes": ["wh:partnerorg/shared-shapes/Deal@v1"],
"validatedShapes": ["wh:partnerorg/shared-shapes/Deal@v1"],
"data": { "temperature": 22.5 },
"durableId": "040SXA5RYM7Q4QXAGM8N6MXYVH5G37TDS2P16YQAG6D6M3VKT6YE8ZCW52H0"
}
}

Edge cases to be aware of:

  • If a thing is removed before its operation is dispatched, the stored payload reports both declaredShapes and validatedShapes as empty arrays.
  • No matched operation carries a kind field.
  • Shape lifecycle operations (matched via a {"kind":"shape"} filter) differ from the default in a few ways:
    • operation.name is hub/shapes/<Name>
    • operation.declaredShapes and operation.validatedShapes are always empty arrays
    • operation.data is present on add and revise operations; operation.reason is present on a retract that supplied one
    • operation.durableId identifies the shape
    • operation.version is never present: only rewrite operations carry version, and a Shape cannot be rewritten

repo.renamed and other graph-scoped metadata subscriptions

Section titled “repo.renamed and other graph-scoped metadata subscriptions”

Graph-scoped metadata deliveries (such as repo.renamed, thing.renamed, and shape.renamed) use a different payload shape. The event field is "warmhub.<eventType>" (for example "warmhub.repo.renamed"). The graph block is present and identifies the graph. The rename payload is delivered under a data field. matchedOperationIndexes and matchedOperations are not present.

FieldDescription
event"warmhub.<eventType>" — for example "warmhub.repo.renamed"
traceIdUnique trace identifier for the event chain
runIdAction run identifier
subscriptionNameName of the subscription that fired
callback_urlCallback endpoint to report asynchronous progress or terminal outcome for this run
graph{ "orgName", "graphName" } — the subscription’s home graph
dataEvent-specific payload (for example, rename details)

Org-scoped metadata deliveries use a similar shape, but graph is null and an org block is present instead.

FieldDescription
event"warmhub.org.renamed"
traceIdUnique trace identifier for the event chain
runIdAction run identifier
subscriptionNameName of the subscription that fired
callback_urlCallback endpoint to report asynchronous progress or terminal outcome for this run
graphnull
org{ "orgName" } — the org the subscription belongs to
dataEvent-specific payload (for example, rename details)

Headers include X-WarmHub-Idempotency-Key, X-WarmHub-Run-Id, and X-WarmHub-Attempt for deduplication and observability. Deliveries also include World Wide Web Consortium (W3C) trace propagation headers such as traceparent and tracestate when they run inside an active backend trace. When the subscription binds a WEBHOOK_SIGNING_SECRET, deliveries are also signed — see Verifying Signatures.

Use callback_url when your handler accepts the request and finishes work asynchronously. Post processing, success, failure, or retry_requested back to that URL using a token with the repo:action-callback scope (or repo:write). For org-scoped runs (such as org.renamed), use a token with the org:action-callback scope instead.

Once the subscription is live, you can inspect what each write delivered. How you do that depends on the subscription’s scope:

  • Graph-scoped subscriptions — use wh sub log with the --graph flag to target the correct graph.
  • Org-scoped subscriptions (such as org.renamed) — wh sub log does not support org-scoped subscriptions. Use the Debugging a Failing Subscription runbook instead.

The Delivery Lifecycle page explains the run statuses, retry schedule, and error codes you will see along the way.

Organization owners and admins can subscribe to these filter-free events:

EventWhen it firesdata payload
org.member_addedA member or pending invite is added{ role, status }
org.repo_createdA private or public graph is created{ graphName, displayName, visibility }
org.repo_publishedAn existing private graph becomes public{ graphName, displayName, visibility: "public" }
org.renamedThe organization slug changes{ oldName, newName }
org.service_account_createdAn owner or admin creates a service accountthe service-account payload plus role
org.service_account_role_changedA service account’s role changesthe service-account payload plus role and previousRole
org.service_account_disabledA service account is disabled, including by archiving the org (one event per account)the service-account payload
org.service_account_enabledA disabled service account is enabledthe service-account payload
org.service_account_deletedA service account is deletedthe service-account payload

The service-account payload is { orgName, orgDurableId, serviceAccount: { name, externalId }, actor: { identityWref }, occurredAt }. serviceAccount.name is {org}/{name}; actor.identityWref is the public wh:warmhub/users/… Identity of the person who made the change (for an archive, the person who archived the org); occurredAt is epoch milliseconds. A change that changes nothing, such as disabling a disabled account, emits no event. Creating a service account never emits org.member_added.

Public graph creation emits org.repo_created only. It does not also emit org.repo_published; publication is reserved for a later real transition from private to public.

Terminal window
wh sub create member-audit --org myorg --event org.member_added \
--webhook-url https://example.com/org-activity
wh sub create graph-feed --org myorg --event org.repo_created \
--webhook-url https://example.com/org-activity
await client.subscription.create({
orgName: 'myorg',
name: 'publication-feed',
kind: 'webhook',
eventType: 'org.repo_published',
webhookUrl: 'https://example.com/org-activity',
})
{
"name": "warmhub_subscription_create",
"arguments": {
"orgName": "myorg",
"scope": "org",
"name": "graph-feed",
"eventType": "org.repo_created",
"kind": "webhook",
"webhookUrl": "https://example.com/org-activity"
}
}

Org event bodies use graph: null, org: { "orgName": "myorg" }, and the payload shown above. They never include internal organization, graph, or user IDs. Member events also omit email, member names, inviter, and actor. Service-account events name the acting person only by their public Identity wref, never by email.

Org activity events differ in how WarmHub checks access before each delivery. For full details on org access rules, see the access reference.

  • org.member_added, org.repo_created, org.repo_published, and the org.service_account_* events — before every delivery attempt, WarmHub rechecks that the subscription creator is still an owner or admin. If the creator has been downgraded, those deliveries are no longer sent.
  • org.renamed — no per-delivery ownership recheck. These subscriptions remain deliverable with standard org:read access.

These webhooks are organization-owned automation. Following graph activity through your personal web app notification or email preferences is a separate notification feature, not an anonymous or outsider webhook subscription.

Write-triggered webhook subscriptions support an optional allowTraceReentry setting.

  • Default: false
  • CLI flag: --allow-trace-reentry
  • Meaning when false: a subscription runs at most once per trace per shape
  • Meaning when true: the subscription may run again within the same trace
  • Hard fuse: a global chain-depth safety limit still applies even when reentry is allowed

You can set allowTraceReentry at create time through any surface: the CLI --allow-trace-reentry flag, the SDK client.subscription.create(...) method, or the MCP warmhub_subscription_create tool. It can also be patched later through MCP with warmhub_subscription_update.

A webhook subscription can watch a source graph that is different from the graph where the subscription lives. When a matching write lands in the source graph, the subscription fires and delivers to the webhook URL configured in its home graph.

  • The source graph must be in the same org as the subscription’s home graph. Cross-org source graphs are rejected at creation time.
  • The subscription creator must have read access to the source graph. Creation fails if this check does not pass.
  • allowTraceReentry applies normally to cross-graph subscriptions.
Terminal window
# Webhook subscription in mygraph that fires on writes to other-graph
wh sub create cross-hook \
--on Sensor \
--kind webhook \
--source myorg/other-graph \
--filter '{"shape":"Sensor"}' \
--webhook-url https://example.com/hook

Cross-graph subscriptions are also supported through the SDK by setting sourceGraphRef on client.subscription.create(...).

await client.subscription.create({
orgName: 'myorg',
graphName: 'mygraph',
name: 'cross-hook',
kind: 'webhook',
shapeName: 'Sensor',
filterJson: { shape: 'Sensor' },
sourceGraphRef: 'myorg/other-graph',
webhookUrl: 'https://example.com/hook',
})

Cross-graph subscriptions are also supported through the warmhub_subscription_create MCP tool by setting sourceGraphRef.

{
"name": "warmhub_subscription_create",
"arguments": {
"orgName": "myorg",
"graphName": "mygraph",
"name": "cross-hook",
"shapeName": "Sensor",
"filterJson": { "shape": "Sensor" },
"sourceGraphRef": "myorg/other-graph",
"webhookUrl": "https://example.com/hook"
}
}

There is no public HTTP subscription creation endpoint for cross-graph or same-graph subscriptions.

Cross-graph deliveries use the same top-level webhook payload shape as same-graph deliveries. Two details matter:

FieldDescription
graphThe subscription’s home graph — where the subscription lives
eventEvent discriminator: "warmhub.write" or "warmhub.retract". Use this field to branch webhook handler logic by event type.
originGraphNameIdentifies the graph where the event originated (read-only).

When the subscription is not cross-graph, the payload shape is still the same.