Let an Agent Write the Webhook, Keep a Human on the Diff
Webhook glue code is where small integrations rot. How Hooksmith lets an agent draft a declarative YAML transform while a human reviews it against a real payload, with signatures verified and stored events you can replay.
Abdul Hamid Achik
Where Small Integrations Rot
Every product accumulates webhook glue. A payment fails and someone needs a message in chat. A deploy finishes and a ticket should update. Each handler is twenty lines, written once, and then it runs unattended for years.
That is why this code rots. The sender changes a field name, the handler throws, and nobody notices until a customer does. The handler often skips signature verification because the first version was a prototype, and nobody revisits it.
An AI agent can write these handlers in seconds, which makes the rot faster unless the process around the agent changes. The useful question is not whether to let the agent draft the transform. It is what a human must be able to review before anything goes live.
Our answer, built into Hooksmith, is a short list of constraints: a small declarative artifact, a real sample payload, verified signatures, and a way to replay what happened.
The Artifact Is Declarative on Purpose
A reviewer cannot audit a generated 200-line handler with retry logic, HTTP calls, and string handling mixed together. They can audit a YAML document with a fixed shape. Hooksmith hooks are hooksmith/v1 documents: a source, a destination, a Handlebars transform, optional conditions, and secrets referenced by name.
Here is the Stripe starter hook from the repo, shortened:
apiVersion: hooksmith/v1
kind: Hook
metadata:
name: stripe
spec:
source:
preset: stripe
destinations:
- name: primary
url: ${DESTINATION_URL}
retries: { max: 3, backoff: exponential, initialDelay: 500ms }
transform:
engine: handlebars
fields:
title: Stripe · {{type}}
message: "{{default data.object.description (default data.object.id related_object.id)}}"
conditions:
- if: type == "charge.dispute.created"
then:
transform:
fields:
title: Stripe dispute opened
interruption_level: critical
variables:
- name: STRIPE_WEBHOOK_SECRET
from: secret
- name: DESTINATION_URL
from: secret
The constraint matters more than the format. Handlebars runs with prototype access disabled, a 200 ms timeout, and no eval. Conditions go through an expression evaluator that never executes arbitrary code. The agent can only produce something the engine is willing to run, so a bad draft fails validation instead of doing damage.
From One Sentence to a Reviewed Diff
The workflow has four steps, and the human stays in the loop on the second and third.
- Describe it. You write the intent: “Alert me when a payment fails, and escalate disputes.” You can attach a real payload from the sender.
- The agent drafts YAML.
hooksmith newcalls the hosted agent when you are logged in, and the system prompt tells it to refer to secrets only as${NAME}and never write a literal credential. If the output fails the same schema the deploy path uses, the agent gets the validation errors and one retry. Invalid YAML never comes back as a success. - Preview against a real payload. You run the transform on a sample before anything ships.
- Deploy. The hook gets a stable endpoint,
https://hooksmith.tech/h/<id>.
hooksmith new stripe-failures \
--instructions "Alert me when a payment fails, escalate disputes" \
--payload ./payment-failed.json
hooksmith test stripe-failures --payload ./payment-failed.json
The test is offline and never calls the destination. We ran the Stripe starter against the repo’s payment_intent.payment_failed fixture and got this:
{
"title": "Stripe payment failed",
"message": "Your card was declined.",
"interruption_level": "time-sensitive"
}
That output is the review. You are not reading a template and imagining the result. You see the message your on-call channel would receive, produced from a payload shaped like the one Stripe sends.
When you regenerate in the terminal UI, the agent’s proposal appears as a line diff. Enter accepts it and Esc keeps your version. The YAML panel is read-only, so the agent writes, you approve, and nothing is edited by accident.
CLI-First, and the Dashboard Only Observes
Hooksmith is local-first and CLI-first. Hooks are YAML files in a local .hooksmith/ folder you can commit, test and dev work offline, and there is no web YAML editor. The README says it directly: create and edit in the CLI or MCP.
The dashboard shows events, payloads, delivery attempts, and usage. It cannot change a transform, and that is deliberate. If production behavior could be edited in a browser tab, the reviewed diff would stop being the source of truth. A YAML file with a visible history is the artifact a human can actually review.
Giving Coding Agents the Same Loop
hooksmith mcp serve starts an MCP server with 13 tools, including generate_transform, create_hook_from_preset, test_hook, deploy_hook, list_events, and replay_event. A coding agent in your editor can run the whole cycle: scaffold, test against a payload, deploy, read the failed event, and fix the YAML.
The tools mirror the CLI instead of adding a second path. test_hook is the same offline evaluation, with request headers filtered the way production filters them. For background on why we expose tools like this over MCP, see Building MCP Servers in Go.
An agent that can deploy still needs a human gate, so we recommend a plain rule: the agent may call create_hook and test_hook freely, and a person reads the YAML before deploy_hook runs. This is the same discipline we describe in Done Is Not Verified: the agent’s claim is not the result, the evidence is.
Signature Verification Is Not Optional
Generated code skips verification more often than hand-written code, because the sample payload carries no signature. Hooksmith moves that decision out of the model’s hands.
A preset fills in the source type and verification scheme for Stripe, GitHub, Meta and WhatsApp, Shopify, Twilio, Resend, and Standard Webhooks. The rules are stricter than the agent’s draft:
- Verification checks the raw request bytes, not a re-serialized body, with constant-time comparisons.
- Stripe and Standard Webhooks enforce a timestamp tolerance, 5 minutes by default, to block replayed requests.
- The secret field must be a single
${NAME}vault reference. A literal secret in YAML is a validation error. - Secrets are write-only:
hooksmith secrets set STRIPE_WEBHOOK_SECRETreads from stdin, and no command returns the value. - A request that fails verification is rejected with HTTP 401 before it is stored.
So the review checklist shrinks to a few lines: the source verification block, the destination URL being a ${...} reference, and the conditions. One of our own internal hooks, which forwards CI build notifications, declares verification: type: none. A reviewer should stop at that line and ask why.
Replay When the Transform Was Wrong
A reviewed draft can still be wrong against production traffic. Hooksmith stores the raw request and its headers, so hooksmith replay <event-id> re-runs the stored event through the hook’s current YAML. Fix the transform, deploy, replay the event that failed, and confirm the output.
Two caveats from the docs matter. A replay sends to every destination again, so anything the destination already did, such as an email or a charge, can happen twice. And a hook with logging.retainPayload: false keeps nothing to replay. Replays skip signature checks and duplicate detection, and they are not counted against your event quota.
What to Take From This
You do not need Hooksmith to apply the pattern. Require a declarative artifact the agent must produce, test it against a real payload before deploy, take verification decisions away from the model, and keep a way to re-run past events.
Start with your own integrations. List every webhook handler you run, and note which ones verify signatures and which have a sample payload on file. Most teams find the gaps in an afternoon. If you want help closing them in an agent-assisted workflow, our agent and AI systems work covers exactly this, and maintaining vibe-coded projects covers what happens when nobody did.
Abdul Hamid Achik
Founder and lead engineer at The Lacanians. Abdul builds production software, developer tools, and local-first systems from Guadalajara for teams worldwide.