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.
Webhook Subscriptions
Section titled “Webhook Subscriptions”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 type | Scope | Description |
|---|---|---|
commit (default) | Graph | Fires 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.renamed | Graph | Fires when the graph itself is renamed. Rejects shapeName, filterJson, and sourceGraphRef. |
thing.renamed | Graph | Fires when a thing in the graph is renamed. Rejects shapeName, filterJson, and sourceGraphRef. |
shape.renamed | Graph | Fires when a shape in the graph is renamed. Rejects shapeName, filterJson, and sourceGraphRef. |
org.renamed | Org | Fires when the org is renamed. Rejects shapeName, filterJson, sourceGraphRef, and graphName. |
org.member_added | Org | Fires when a member or pending invite is added. Rejects shapeName, filterJson, sourceGraphRef, and graphName. |
org.repo_created | Org | Fires when a private or public graph is created. Rejects shapeName, filterJson, sourceGraphRef, and graphName. |
org.repo_published | Org | Fires 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_deleted | Org | Fire 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.
Access and grants
Section titled “Access and grants”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.
Webhook URL Requirements
Section titled “Webhook URL Requirements”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, or8443. Other ports (for example25,22, or6379) 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 as10.0.0.0/8and192.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-encoded127.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.
Redirect behavior
Section titled “Redirect behavior”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.
Two failure modes at validate time
Section titled “Two failure modes at validate time”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.
Via CLI
Section titled “Via CLI”# Default commit subscriptionwh sub create sensor-hook \ --on Sensor \ --kind webhook \ --filter '{"shape":"Sensor"}' \ --webhook-url https://example.com/hook
# Graph rename subscriptionwh sub create graph-rename-hook \ --kind webhook \ --event repo.renamed \ --webhook-url https://example.com/hook
# Org rename subscriptionwh 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 webhookwh sub create sensor-loop \ --on Sensor \ --kind webhook \ --filter '{"shape":"Sensor"}' \ --webhook-url https://example.com/hook \ --allow-trace-reentryVia MCP
Section titled “Via MCP”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.
Webhook Payload
Section titled “Webhook Payload”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".
commit subscriptions (default)
Section titled “commit subscriptions (default)”| Field | Description |
|---|---|
event | "warmhub.write" or "warmhub.retract" |
traceId | Unique trace identifier for the event chain |
runId | Action run identifier |
subscriptionName | Name of the subscription that fired |
callback_url | Callback endpoint to report asynchronous progress or terminal outcome for this run |
graph | { "orgName", "graphName" } — the subscription’s home graph |
graphSeq | The 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. |
matchedOperationIndexes | Indexes of operations that matched the filter |
matchedOperations | The matched operations. See the field details below. |
matchedOperations field details
Each entry in matchedOperations is a wrapper object with two fields:
| Field | Type | Description |
|---|---|---|
index | number | Position of this operation in the original write |
operation | object | The operation details — see the sub-fields below |
The operation details live inside the nested operation object:
| Field | Description |
|---|---|
operation | The operation verb (for example "add", "revise", "retract", "rewrite"); use this to distinguish the kind of change |
name | The thing’s short name as stored (for example cave or acme), or hub/shapes/<Name> for a shape operation |
declaredShapes | Pinned 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). |
validatedShapes | Pinned 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). |
data | Present when the operation carries a data payload |
durableId | The 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
declaredShapesandvalidatedShapesas empty arrays. - No matched operation carries a
kindfield. - Shape lifecycle operations (matched via a
{"kind":"shape"}filter) differ from the default in a few ways:operation.nameishub/shapes/<Name>operation.declaredShapesandoperation.validatedShapesare always empty arraysoperation.datais present on add and revise operations;operation.reasonis present on a retract that supplied oneoperation.durableIdidentifies the shapeoperation.versionis never present: only rewrite operations carryversion, 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.
| Field | Description |
|---|---|
event | "warmhub.<eventType>" — for example "warmhub.repo.renamed" |
traceId | Unique trace identifier for the event chain |
runId | Action run identifier |
subscriptionName | Name of the subscription that fired |
callback_url | Callback endpoint to report asynchronous progress or terminal outcome for this run |
graph | { "orgName", "graphName" } — the subscription’s home graph |
data | Event-specific payload (for example, rename details) |
org.renamed subscriptions
Section titled “org.renamed subscriptions”Org-scoped metadata deliveries use a similar shape, but graph is null and an org block is present instead.
| Field | Description |
|---|---|
event | "warmhub.org.renamed" |
traceId | Unique trace identifier for the event chain |
runId | Action run identifier |
subscriptionName | Name of the subscription that fired |
callback_url | Callback endpoint to report asynchronous progress or terminal outcome for this run |
graph | null |
org | { "orgName" } — the org the subscription belongs to |
data | Event-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 logwith the--graphflag to target the correct graph. - Org-scoped subscriptions (such as
org.renamed) —wh sub logdoes 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 Activity Subscriptions
Section titled “Organization Activity Subscriptions”Organization owners and admins can subscribe to these filter-free events:
| Event | When it fires | data payload |
|---|---|---|
org.member_added | A member or pending invite is added | { role, status } |
org.repo_created | A private or public graph is created | { graphName, displayName, visibility } |
org.repo_published | An existing private graph becomes public | { graphName, displayName, visibility: "public" } |
org.renamed | The organization slug changes | { oldName, newName } |
org.service_account_created | An owner or admin creates a service account | the service-account payload plus role |
org.service_account_role_changed | A service account’s role changes | the service-account payload plus role and previousRole |
org.service_account_disabled | A service account is disabled, including by archiving the org (one event per account) | the service-account payload |
org.service_account_enabled | A disabled service account is enabled | the service-account payload |
org.service_account_deleted | A service account is deleted | the 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.
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-activityawait 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 theorg.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 standardorg:readaccess.
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.
Advanced
Section titled “Advanced”Trace Reentry
Section titled “Trace Reentry”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.
Cross-Graph Subscriptions
Section titled “Cross-Graph Subscriptions”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.
Constraints
Section titled “Constraints”- 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.
allowTraceReentryapplies normally to cross-graph subscriptions.
Via CLI
Section titled “Via CLI”# Webhook subscription in mygraph that fires on writes to other-graphwh sub create cross-hook \ --on Sensor \ --kind webhook \ --source myorg/other-graph \ --filter '{"shape":"Sensor"}' \ --webhook-url https://example.com/hookVia SDK
Section titled “Via SDK”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',})Via MCP
Section titled “Via MCP”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.
Payload Differences
Section titled “Payload Differences”Cross-graph deliveries use the same top-level webhook payload shape as same-graph deliveries. Two details matter:
| Field | Description |
|---|---|
graph | The subscription’s home graph — where the subscription lives |
event | Event discriminator: "warmhub.write" or "warmhub.retract". Use this field to branch webhook handler logic by event type. |
originGraphName | Identifies the graph where the event originated (read-only). |
When the subscription is not cross-graph, the payload shape is still the same.