Building Event-Driven AI Agents with Webhook Triggers

Most AI agents are built request-response. You call the agent, it answers. That works for chat, and it misses the point.

The interesting agents react to the world on their own. A support ticket lands. A deploy fails. A customer churns. An anomaly shows up in the metrics. Each of those is a moment where an agent should act, and nobody is there to press the button.

The Problem with Polling

The naive fix is a loop: check Slack every 30 seconds, query the database every minute, hit the GitHub API forever.

Do the math on a 30-second poll. Your median detection delay is 15 seconds and your worst case is 30. You make 2,880 requests a day per source to discover maybe a dozen events, so more than 99% of your calls return nothing. Tighten the interval and the rate limiter pushes back. Loosen it and the latency grows. Polling forces you to choose between wasteful and slow, and it still misses events during downtime.

Webhooks Invert the Model

Instead of your agent asking "did anything happen?", the services that know push the event the moment it occurs.

On Maritime, every agent gets a webhook endpoint out of the box:

POST https://api.maritime.sh/api/webhooks/{agent-id}

When a webhook hits this endpoint, Maritime wakes your agent if it is sleeping, hands it the payload, and lets it decide what to do. Zero requests at rest, sub-second reaction when something happens.

Real-World Examples

GitHub Push → Auto-Review Agent

Register a webhook trigger, then point your repo's webhook settings (Settings → Webhooks) at your agent's endpoint. On every push, the agent pulls the diff, reviews the code, and comments on the PR.

maritime triggers create my-agent --type webhook

Stripe Payment → Onboarding Agent

A customer pays, Stripe fires an event, your agent provisions the account, sends the welcome email, and updates the CRM. No human in the loop.

Slack Message → Knowledge Agent

A teammate asks a question in a channel. The agent gets the message event, searches your internal docs, and answers in the thread.

Monitoring Alert → Incident Agent

Datadog detects an anomaly and fires a webhook. The agent triages, checks recent deploys, and opens a PagerDuty incident with the context already attached.

Combining Triggers

Triggers compose. A common pattern for a billing agent:

1. Webhook trigger. React to Stripe payment events as they happen
2. Cron trigger. Sweep for failed charges every morning
3. API trigger. Let the support team invoke it manually for edge cases

All three point at the same agent. Each delivery wakes it if it is sleeping, counts as one invocation, and resets the idle timer.

maritime triggers create my-agent --type webhook
maritime triggers create my-agent --type cron --cron "0 9 * * *"

Payload Processing

Your agent receives the raw webhook payload as JSON, delivered as a message the moment it is awake. Parsing the event type, routing to the right tool, or ignoring the event entirely is agent logic, which is exactly where that decision belongs. Every delivery is also recorded in the agent's log stream, so you can see what came in and when.

One practical note: most providers deliver at-least-once, not exactly-once. Keep a seen-set keyed on the provider's event ID (Stripe's evt_ IDs, GitHub's delivery GUID) and skip duplicates. It is three lines of agent code and it saves you from double-provisioning a customer.

Security

Treat your agent's webhook URL like a credential. The agent ID in the path is what gates delivery, so share the URL only with services that should be able to reach the agent. And because webhook payloads are untrusted input, validate them in your agent logic before acting: check that the fields you expect are present and well-formed, exactly as you would with user input in a web app.

Getting Started

If your agent is already on Maritime, event-driven is one command away:

maritime triggers create my-agent --type webhook

The agent sleeps until something happens, wakes to handle it, and goes back to sleep. That is the whole model, and it is the right one for agents that respond to a world that mostly is not talking to them.