Guide
How to let an AI agent write and deploy webhook transforms
Register hooksmith mcp serve as an MCP server in your AI client and log in with the CLI. The agent can then call Hooksmith tools to scaffold or generate a hook, edit its YAML, test it against a payload, deploy it for an ingest URL, and read events back. Secrets stay with you: no MCP tool reads or sets one, so you store them with hooksmith secrets set yourself.
Before you start
- The Hooksmith CLI, installed and logged in (curl -fsSL https://hooksmith.tech/install.sh | bash, then hooksmith login). The MCP server reads the token from ~/.hooksmith/credentials.json, or from HOOKSMITH_TOKEN.
- An AI client that supports MCP servers over stdio and lets you add one with a command, args and env.
- A project directory. The agent writes hooks to .hooksmith/hooks/ inside it.
Steps
Step 1: Create a workspace for the hooks
Run this in the directory the agent will work in. The MCP server reads and writes .hooksmith/hooks/<name>.yaml under the directory named by HOOKSMITH_WORKSPACE, or under its current directory if that variable is unset.
terminalhooksmith init
Step 2: Add the server to your AI client
Add this entry to your client's MCP configuration. hooksmith mcp serve speaks MCP over stdio.
Set HOOKSMITH_WORKSPACE to the absolute path of the project from the previous step. The MCP server talks to https://hooksmith.tech by default from CLI 0.6.2 on. Older versions fell back to http://127.0.0.1:8787, the local development API, so keeping HOOKSMITH_API_URL in the env block makes the configuration work on any version.
Some clients start servers without your shell's PATH. If yours cannot find the command, put the absolute path from which hooksmith in command. The CLI starts with #!/usr/bin/env bun, so bun must be on that PATH as well.
MCP client configuration{ "mcpServers": { "hooksmith": { "command": "hooksmith", "args": ["mcp", "serve"], "env": { "HOOKSMITH_API_URL": "https://hooksmith.tech", "HOOKSMITH_WORKSPACE": "/absolute/path/to/your/project" } } } }Step 3: Tell the agent what the hook should do
Name the provider, the condition and the destination in one request. The agent picks the tools. For a provider Hooksmith has a preset for, it can call list_presets and create_hook_from_preset, which fill in verification and the secret names. For anything else it calls generate_transform, which uses the hosted agent and counts toward your plan's monthly generations.
An example request:
promptCreate a Hooksmith hook named resend-bounces for Resend. When an email bounces or is marked as spam, send a one-line message with the subject and recipient to my chat webhook. Ignore every other event. Test it with a sample bounce, then show me the YAML before you deploy.
Step 4: Review the YAML the agent wrote
The agent reads a hook back with get_hook and changes it with edit_transform, which rejects YAML that does not parse as a hooksmith/v1 hook before writing it. Ask it to show you the diff. A hook like the one below is what a good result looks like; yours will differ.
Keep the destination as ${DESTINATION_URL}. The offline test_hook tool, like hooksmith test, only knows the secrets BRRR_WEBHOOK, BUILDKITE_TOKEN and DESTINATION_URL.
.hooksmith/hooks/resend-bounces.yamlapiVersion: hooksmith/v1 kind: Hook metadata: name: resend-bounces description: Resend bounces and complaints to chat spec: source: preset: resend destinations: - name: primary url: ${DESTINATION_URL} method: POST timeout: 8s retries: max: 3 backoff: exponential initialDelay: 500ms transform: engine: handlebars fields: text: "{{type}}: {{{data.subject}}} to {{data.to.[0]}}" conditions: - if: type != "email.bounced" && type != "email.complained" then: skip: true variables: - name: RESEND_WEBHOOK_SECRET from: secret - name: DESTINATION_URL from: secretStep 5: Have the agent test it
test_hook evaluates the hook against a payload you or the agent supply and returns skipped, the rendered body and the destination names. It never calls a destination. Try a payload that should pass and one that should be skipped.
payload for test_hook{ "type": "email.bounced", "data": { "subject": "Your receipt", "to": ["ada@example.com"] } }Step 6: Store the secrets yourself
The agent can tell you which secrets the hook needs, but it cannot set them. Run these in your terminal. The Resend signing secret comes from the webhook you add in Resend.
terminalhooksmith secrets set DESTINATION_URL printf %s "$RESEND_SECRET" | hooksmith secrets set RESEND_WEBHOOK_SECRET
Step 7: Deploy it
Ask the agent to call deploy_hook. It returns the hook's id and its ingest url, which looks like https://hooksmith.tech/h/<id>. Paste that URL into the provider's webhook settings.
Step 8: Let the agent watch and repair it
list_events returns the recent events of a deployed hook. When a delivery fails, fix_with_agent returns the hook's YAML, the last error and the commands to repair it. replay_event re-runs a stored event through the hook once the fix is deployed. The dashboard's Fix with Agent button copies a prompt that calls fix_with_agent.
How to check it works
Check the result outside the agent's own report.
- hooksmith list shows the hook file the agent wrote, and hooksmith show resend-bounces prints its YAML.
- hooksmith test resend-bounces --payload ./bounce.json gives the same result the agent reported from test_hook.
- After the provider sends an event, hooksmith logs resend-bounces lists it as delivered, or as skipped if your conditions dropped it.
hooksmith list hooksmith show resend-bounces hooksmith test resend-bounces --payload ./bounce.json hooksmith logs resend-bounces
Troubleshooting
Not authenticated. Run hooksmith login or set HOOKSMITH_TOKEN.
The server found no token. Run hooksmith login as the same user the client runs as, or add HOOKSMITH_TOKEN to the env block.
The tool result has source: "mock" and a notice such as generated an offline template instead.
generate_transform and create_hook fell back to an offline template for a Buildkite hook, which is not what you asked for. The notice says why, for example the hosted agent answered with an HTTP error. Ask the agent to write the YAML itself and save it with edit_transform, or use a preset.
deploy_hook returns DEPLOY_FAILED, or tool calls fail with a connection error.
On CLI 0.6.1 and earlier the MCP server called http://127.0.0.1:8787 unless told otherwise. Update the CLI, or set HOOKSMITH_API_URL to https://hooksmith.tech in the client's env block, and restart the client.
Hook not found: resend-bounces
The server looked in the wrong directory. It reads .hooksmith/hooks/ under HOOKSMITH_WORKSPACE, or under its current directory. Set HOOKSMITH_WORKSPACE to your project path.
Hook not deployed: resend-bounces
list_events only works for a deployed hook. Call deploy_hook first.
REPLAY_FAILED
replay_event was refused. The event id may belong to another workspace, the hook may be deleted, or the event was received with logging.retainPayload: false.
Secret not found: RESEND_WEBHOOK_SECRET
Store the secret in your terminal with hooksmith secrets set. The agent has no tool for it.