Skip to content

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

  1. 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.

    terminal
    hooksmith init
  2. 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"
          }
        }
      }
    }
  3. 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:

    prompt
    Create 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.
  4. 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.yaml
    apiVersion: 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: secret
    
  5. Step 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"] }
    }
  6. 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.

    terminal
    hooksmith secrets set DESTINATION_URL
    printf %s "$RESEND_SECRET" | hooksmith secrets set RESEND_WEBHOOK_SECRET
  7. 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.

  8. 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.
terminal
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.