Create and edit hooks
Create a hook with the TUI: the agent drafts the YAML, you read the live preview and approve. This page covers the agent fallbacks, conditions that read the body or request headers, editing over MCP and quiet hours.
Docs pagesCreate and edit hooks
On this pageCreate a hook
Create a hook
new opens the TUI: the agent drafts the YAML, you read the live preview and approve. When you are logged in, the draft comes from the hosted agent. Each hosted draft counts toward your plan's monthly agent generations: 50 on Free and 1,000 on Pro, per workspace, reset on the first of each month (UTC). Requests refused before the agent runs do not count.
If the hosted agent cannot answer, the CLI falls back in this order. When it falls back, it prints one line on stderr saying why. The only case that prints nothing is a logged-out draft that a local key handles.
- Not logged in, out of generations for the month, unavailable, or it returned an invalid hook twice: a local AI_GATEWAY_API_KEY in your environment is used if set. This is for self-hosting.
- Otherwise an offline template is written, which you then edit in the TUI or your editor.
- --preset skips the agent entirely. --agent mock, HOOKSMITH_AGENT=mock or HOOKSMITH_OFFLINE=1 forces the offline template with no notice.
In edit, the TUI's regenerate key (Ctrl+R) sends the current YAML, so the agent changes the hook you have. In new, it asks for a fresh draft. test runs the conditions and the transform against a sample payload locally.
hooksmith init hooksmith new stripe-failed-payments --instructions "Alert me when a payment fails" hooksmith test stripe-failed-payments --payload ./event.json
Conditions and headers
spec.conditions is a list of rules. Each has an if expression and a then block. With skip: true the event is stored as skipped and no destination is called; with a transform the rule overrides fields. Rules run top to bottom. An expression reads the parsed JSON body by path, such as data.object.amount_due, and supports ==, !=, <, <=, >, >=, &&, ||, ! and parentheses. Write text literals in quotes.
Request headers. An expression reads a header as @headers.x-github-event, or @headers["x-github-event"]. A template reads it as {{@headers.x-github-event}}, which also works inside {{#each}}. A header that is not on the request is empty.
Names are lowercase. Hooksmith stores header names in lowercase, so @headers.X-GitHub-Event could never match. It is a validation error when you test or deploy, and the message gives the lowercase spelling: use @headers.x-github-event instead of @headers.X-GitHub-Event.
Which headers a hook sees. The hook sees the headers Hooksmith stores with the event, and no others. Never visible: Authorization, Proxy-Authorization, cookies, x-api-key, api-key, apikey, x-auth-token, x-access-token, connection headers such as host and content-length, and proxy and edge headers such as x-forwarded-*, x-vercel-* and cf-*. If the hook verifies a shared secret with verification.type: header, that header is hidden too. Signature headers such as x-hub-signature-256 are kept. Header values over 2,048 characters are not kept.
Replays re-run the stored request with its stored headers, so a replay takes the same path through the conditions as the original.
Testing. A test has no provider headers such as X-GitHub-Event unless you add them. Without it @headers.x-github-event is empty, and the example here skips the event. From the terminal, pass --header "Name: value", repeated for each header (CLI 0.6.4 or later). In the dashboard, Send test event on the hook's page has a collapsible Headers box with one Name: value per line, up to 32. The test API accepts the same as a headers object next to payload. In a dashboard test, Hooksmith sets content-type, x-request-id and x-hooksmith-test itself, and they replace a header of the same name that you enter.
apiVersion: hooksmith/v1
kind: Hook
metadata:
name: github-pushes
description: Pushes only, with the event name from the header
spec:
source:
preset: github
destinations:
- name: primary
url: ${DESTINATION_URL}
method: POST
timeout: 8s
transform:
engine: handlebars
fields:
event: "{{@headers.x-github-event}}"
repo: "{{repository.full_name}}"
conditions:
- if: '@headers.x-github-event != "push"'
then:
skip: true
variables:
- name: GITHUB_WEBHOOK_SECRET
from: secret
- name: DESTINATION_URL
from: secret
hooksmith test github-pushes --payload ./push.json --header "X-GitHub-Event: push"
Agent / MCP
The MCP server exposes the whole lifecycle as tools: list_presets and create_hook_from_preset, edit_transform, test_hook, deploy_hook, and list_events with replay_event. It also includes fix_with_agent for repairing a failing hook from a real event. The dashboard's "Fix with Agent" button copies a prompt that calls it.
hooksmith mcp serve
Quiet hours
Add spec.quietHours so a destination stays quiet overnight. mode: defer queues the event and delivers the original payload when the window ends. mode: mute delivers now with interruption_level: passive and no sound.
quietHours:
timezone: America/Mexico_City
window: "22:00-08:00"
mode: defer
applyTo:
- slack-alerts