Article · Updated November 8, 2026 · By the Hooks team
Trigger an AI agent from a webhook
Short answer: To trigger an AI agent from a webhook, point the provider at a gateway endpoint, filter to the events that matter, render a task payload with a template, and forward it to the agent's HTTP endpoint. The gateway keeps the retries and delivery log, so a temporarily unavailable agent does not lose the event.
The hard part is not the HTTP call; it is deciding which events deserve an agent run, and what the agent should receive. Both are configuration, not code.
The four steps
1. Create an endpoint and give the provider its URL, so GitHub, Stripe, or Linear starts posting there.
2. Add a filter. A push to the default branch is usually worth an agent run; a bot comment rarely is.
3. Add a template that builds the agent task from the event: fixed instruction text plus selected event fields.
4. Add the agent's destination URL and a secret. Hooks signs each forwarded request, and retries with exponential backoff if the agent is down.
Keep the task envelope small
Pass the fields the agent needs and a stable event id, not the entire provider payload. Smaller envelopes are cheaper to process, easier to audit, and less exposed to prompt injection from user-controlled fields such as issue titles or commit messages.
Template
{
"task": "Summarize this push and list risky changes",
"event_id": "{{ event.id }}",
"repo": "{{ event.subject.name }}",
"compare_url": "{{ event.payload.compare }}"
}When the agent is offline
Hooks accepts and stores the event before it calls the agent, so a short outage does not lose it. A 2xx from the agent means the task was accepted and queued, not that the work finished; the agent runs asynchronously.
Delivery is at-least-once. Agent targets retry three times starting about 15 seconds apart by default; a generic HTTP destination retries five times starting at about 2 seconds. Every attempt carries the same delivery id. When attempts run out the delivery becomes dead, and you replay the stored event after the agent is healthy.
A replay creates new delivery attempts against the same destinations. The agent must therefore deduplicate on the delivery id or its own run id; no webhook gateway can offer exactly-once execution of your side effects.
Reproduce the failure and recovery locally
# Prerequisites: a local dev stack and a built CLI
pnpm dev
pnpm --filter @hooks/cli build
pnpm e2e:agent-recovery
# A signed GitHub issue is accepted, the mock agent returns 503,
# the delivery is recorded, the replay settles it after recovery,
# and a duplicate X-GitHub-Delivery never reaches the agent twice.
# Expected: "7 checks passed"What the local demo does and does not prove
The demo keeps shipped behavior separate from mocks. Signature verification, the label filter, failed-delivery records, replay and duplicate suppression run against the real local stack. The agent is a local mock: it returns a run id and fails once on purpose, and no model is called.
Real write-back into Hooks — sessions, progress and completion callbacks — depends on open issue #95 and is not available yet. The demo stops at “agent accepted”, which is the same boundary a production delivery log shows today.
Frequently asked questions
Which agents work as a Hooks destination?
Any HTTPS endpoint that accepts a JSON POST, including Grok Bot routines, t3code, and Paseo. The target guides cover the request shape each one expects.
Should the agent receive the raw provider payload?
Prefer a template with the fields you need. Forwarding the raw body hands the agent every user-controlled string in the event, which is exactly the input prompt injection relies on.
Try the flow without an account
Send a test webhook to a temporary endpoint and watch signature verification and forwarding. No account, card, or paid model call is involved.