Subscriptions

A subscription watches a repository for changes and executes an action when matching commits land or a cron schedule fires. Subscriptions are WarmHub’s mechanism for automation — webhook calls, script execution, and scheduled tasks.

A subscription can watch its own repository (the default) or a different repository in the same org (a cross-repo subscription). In both cases the executor runs in the subscription’s home repository context.

How Subscriptions Work

When a commit is applied to a repository, WarmHub evaluates all active subscriptions:

1. Event created — one action event per commit
2. Filter matching — each subscription’s filter is compared against the commit’s operations; this includes subscriptions in other repos that are configured to watch the source repo
3. Dispatch — matching subscriptions trigger their configured executor (webhook or sprite)
4. Retry — failed deliveries are retried with exponential backoff

Cron subscriptions skip steps 1–2 and fire on their schedule directly.

Three Kinds

Kind	Trigger	Executor	Use Case
webhook	Commit	HTTP POST to your URL	Notify external services, trigger pipelines
sprite	Commit	Remote command execution	Run code in response to changes
cron	Schedule	Webhook or sprite	Periodic health checks, syncs, reports

Webhook

Sends an HTTP POST to the configured URL whenever matching operations are committed. The payload includes the commit details, matched operations, and tracing metadata. Webhook subscriptions support credential binding for authentication.

Sprite

Executes a command in a sandboxed remote environment. Sprite subscriptions can optionally clone a GitHub repository and run your code at a specific ref. The matched commit data is delivered as input (via stdin, JSON file, or environment variables).

Cron

Fires on a cron schedule (minimum 5-minute interval) and delegates to either a webhook or sprite executor. Cron subscriptions are not bound to a shape and do not filter operations — they simply run on schedule.

Filter Matching

Webhook and sprite subscriptions are bound to a shape and carry a filter that determines which operations trigger the action. Only operations on the subscription’s shape are evaluated.

Filters support matching on:

• operation — add, revise
• kind — shape, thing, assertion, collection
• shape — shape name (resolved to ID at creation time for rename safety)
• namePrefix — prefix match on the operation’s thing name

Boolean combinators all, any, and not allow compound filters. See Filter JSON Reference for the full grammar.

Cross-Repo Subscriptions

A subscription can watch a shape in a different repository within the same org. The subscription lives in its home repo (where its executor is configured and credentials are resolved), but its filter is evaluated against commits in the source repo.

When a commit lands in the source repo, WarmHub fans out to all cross-repo subscribers watching that repo’s shapes in addition to the repo’s own local subscribers. The executor always runs in the subscription’s home repo context. For sprite subscriptions, the action payload includes both a repo field (the home repo) and a sourceRepo field (the repo where the commit occurred).

Lifecycle

Subscriptions have two states:

• Active — events are matched and dispatched normally
• Paused — no new deliveries are created; cron jobs are deregistered

Pausing and resuming are instant operations. See Managing Subscriptions for details.

Retry Behavior

Failed deliveries are retried up to 5 attempts with exponential backoff:

Attempt	Delay
1	Immediate
2	1 second
3	2 seconds
4	4 seconds
5	8 seconds

Retryable conditions: network errors, HTTP 429 (rate limit), HTTP 5xx (server errors).

Non-retryable (terminal): HTTP 4xx (except 429), validation errors, missing configuration.

After all retries are exhausted, the run transitions to dead_letter. Non-retryable errors immediately become failed_terminal. Both terminal states create a notification.

Notifications

WarmHub emits in-app notifications for subscription delivery outcomes.

Failure notifications are always enabled. A notification is created whenever a run reaches a terminal failure state (dead_letter or failed_terminal).

Success notifications are opt-in via a notifyOnSuccess flag on the subscription. This flag is not yet configurable through the CLI, HTTP API, or MCP tools and will be exposed through the standard interfaces in a future release.

Observability

Every subscription maintains a delivery feed — a chronological log of action deliveries with status, matched operations, and associated commits. Each delivery tracks individual attempts with HTTP status codes, error messages, and response snippets.

# View recent deliveries
wh sub log signal-hook

# Follow deliveries in real time
wh sub log signal-hook --live

See Managing Subscriptions for the full observability surface.

Next Steps

• Creating Subscriptions — set up webhook, sprite, and cron subscriptions with filters and credentials
• Managing Subscriptions — monitor, pause, resume, and delete subscriptions