Automations

Automations let you run versioned logic in the event path before the transformed delivery snapshot reaches your agent or downstream destination. The public feature name is Automations; Code Mode is the code-powered transform mode inside Automations.

Automation model

An automation belongs to one project and can be bound to one webhook as a delivery-path transform. For this launch, the public automation type is transform.

The model has three layers:

• automation metadata: name, slug, status, limits, active version, optional webhook binding, and optional Enterprise egress policy
• immutable versions: uploaded JavaScript bundles with compatibility settings and code hashes
• runs: recorded invocations with result type, logs, bounded previews, quota usage, and egress audit events

Create the automation shell first, upload one or more versions, activate a version, then bind the automation to a webhook.

hooksbase automations create --webhook wh_123 --name "Normalize agent event" --json
hooksbase automations versions create auto_123 --file ./transform.js --activate --json
hooksbase automations bind wh_123 auto_123 --json

Code Mode transforms

Code Mode transforms are JavaScript transforms that run after routing resolves and before outbound delivery is persisted. They are useful when JSONPath or Handlebars transforms are too limited and your agent needs a normalized, guarded, or enriched event contract.

Use Code Mode for event-path logic such as:

• normalizing provider-specific payloads into one agent input shape
• dropping fields your agent should not receive
• adding derived fields from headers or payload content
• returning a new JSON body, a no-op pass-through result, or a rejected result

Classic payload transforms remain available for constrained JSONPath and Handlebars reshaping.

Input and output contract

Code Mode runs export async function run(input). The supported input context includes:

• input.source.payload: the automation input payload
• input.source.headers: inbound headers normalized for lookup
• input.source.contentType: the accepted source content type
• metadata needed to associate the run with the project, webhook, automation, and version

Delivery-path transforms usually receive a payload object containing payload, provider, webhook, route, and baselineDispatch. The transform must return a supported result. Result types are intentionally small so delivery behavior stays deterministic:

• continue: deliver the existing baseline dispatch snapshot
• dispatch: replace the outbound dispatch body
• respond: return a custom response-shaped result
• thrown errors: record the run as failed

The returned dispatch body should remain JSON for delivery-path transforms. Automations do not mutate the destination URL, HTTP method, or outbound headers.

Versioning and test runs

Every uploaded Code Mode bundle creates an immutable version. Activating a version changes what future events use; it does not rewrite existing delivery history.

import { createHooksbaseClient } from '@hooksbase/sdk'

const client = createHooksbaseClient({
  apiKey: process.env.HOOKSBASE_API_KEY,
})

await client.automations.createVersion('auto_123', {
  code: 'export async function run(input) { return { type: "dispatch", body: input.source.payload } }',
  compatibilityDate: '2026-05-02',
})

await client.automations.test('auto_123', {
  payload: { provider: 'stripe', type: 'invoice.payment_failed' },
  waitForSettlementMs: 3000,
})

Test runs are recorded in the same run ledger as delivery-path runs, with run kind metadata so you can filter and inspect them separately.

Runs, logs, and replay behavior

Runs capture status, result type, code hash, input size, response status, bounded result preview, log byte counts, egress counts, limits, and timestamps.

hooksbase automations runs list --automation auto_123 --limit 20 --json
hooksbase automations runs get run_123 --json
hooksbase automations logs run_123 --json
hooksbase automations runs export --format csv --automation auto_123 --from 1777670400000 --to 1777756800000 --limit 100

Replay stays tied to persisted delivery artifacts. Retries, single replay, DLQ re-drive, and bulk replay use the dispatch snapshot saved with the original delivery. They do not re-run the latest active automation version.

Quotas and metering

Automations are available on Starter, Pro, Business, and Enterprise when the runtime is enabled for the deployment. Free projects cannot save or run Automations.

Quota state is available at project and webhook scope:

• GET /v1/automation-quotas
• GET /v1/webhooks/{id}/automation-quotas
• hooksbase automations quotas --json
• hooksbase automations quotas --webhook wh_123 --json

Raw automation metering is provider-neutral. It reports settled runs, CPU milliseconds, subrequests, log bytes, unique worker creations, egress attempts, and blocked egress attempts. This endpoint does not enqueue Stripe or Polar usage events.

hooksbase automations usage --month 2026-05 --json

Enterprise egress

Default Automation egress is blocked. Starter, Pro, and Business can run delivery-path Automations with default egress blocked unless Hooksbase support attaches a policy. Enterprise projects can self-manage exact-host egress policies and gateway credentials.

Enterprise egress policy controls are explicit:

• hosts are exact hostnames, not wildcard domains
• allowed HTTP methods are policy-scoped
• request and response body limits are policy-scoped
• credentials are stored as secret versions and never returned as plaintext
• run-level egress audit events show allowed, blocked, and credential-injected attempts

hooksbase automations egress create --file ./egress-policy.json --json
hooksbase automations egress credentials create pol_123 \
  --name "CRM token" \
  --host api.example.com \
  --secret-file ./secret.txt \
  --json
hooksbase automations egress attach auto_123 pol_123 --json

Unsupported surfaces

Automations are deliberately scoped for launch:

• no Free-tier runtime
• no public arbitrary JavaScript playground
• no AI code-generation claim or automatic code authoring
• no multi-step workflow builder
• no destination URL, HTTP method, or header mutation
• no static outbound IP guarantee
• no self-service egress policy management below Enterprise

Use the dashboard for human authoring and the public API, SDK, or CLI for repeatable machine operations. Do not build against browser implementation routes.

Common mistakes

• Calling the feature Code Mode in navigation or top-level docs. Code Mode is a mode inside Automations.
• Expecting replay to execute the current active version. Replay uses the saved dispatch snapshot.
• Adding outbound fetch calls on non-Enterprise projects and expecting them to work without an attached policy.
• Treating logs or result previews as unbounded storage.
• Updating automation metadata and expecting that to upload a new code version.