Building Event-Driven AI Agents with Webhook Triggers

Most AI agents are built to respond to direct API calls. You send a request, the agent processes it, you get a response. That works for chatbots and simple Q&A, but it misses the bigger picture.

The real power of AI agents comes when they react to events autonomously. A new support ticket lands in your inbox. A deploy fails in CI. A customer churns. An anomaly appears in your metrics. These are moments where an agent should act — without someone manually triggering it.

The Problem with Polling

The naive solution is to have your agent poll for changes. Check Slack every 30 seconds. Query your database every minute. Hit the GitHub API on a loop.

This is wasteful, slow, and fragile:

• Wasteful — Your agent wakes up hundreds of times to find nothing new
• Slow — There's always a delay between the event and your agent noticing it
• Fragile — API rate limits, network errors, and missed events during downtime

Webhooks Change Everything

Webhooks invert the model. Instead of your agent asking "did anything happen?", external services push events to your agent the moment they occur.

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

POST https://api.maritime.sh/v1/agents/{agent-id}/webhook

When a webhook hits this endpoint, Maritime wakes your agent, passes the payload, and lets your agent decide what to do with it. No polling, no wasted compute, sub-second latency.

Real-World Examples

GitHub Push → Auto-Review Agent

Configure GitHub to send push events to your agent. On every commit, your agent pulls the diff, reviews the code, and posts comments on the PR.

maritime trigger add --type webhook --source github --events push,pull_request

Stripe Payment → Onboarding Agent

When a customer pays, Stripe sends a webhook. Your agent receives it, provisions their account, sends a welcome email, and updates your CRM — all without human intervention.

Slack Message → Knowledge Agent

A team member asks a question in a Slack channel. Your agent receives the message event, searches your internal docs, and replies with an answer in the thread.

Monitoring Alert → Incident Agent

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

Combining Triggers

Webhooks become even more powerful when combined with other trigger types. A common pattern:

1. Webhook trigger — Agent reacts to a Stripe payment event
2. Cron trigger — Same agent runs daily to check for failed charges
3. API trigger — Support team can manually invoke the agent for edge cases

All three triggers point to the same agent. Maritime handles deduplication and concurrency, so you don't process the same event twice.

maritime trigger add --type webhook --source stripe
maritime trigger add --type cron --schedule "0 9 * * *"

Payload Processing

Your agent receives the raw webhook payload as JSON. Maritime adds metadata headers so your agent knows the source and event type:

• X-Maritime-Source — The configured source (github, stripe, slack, etc.)
• X-Maritime-Event — The specific event type
• X-Maritime-Delivery — Unique delivery ID for idempotency
• X-Maritime-Timestamp — When the event was received

Security

Webhook endpoints on Maritime are authenticated by default. You can configure signature verification for each source — HMAC for GitHub, Stripe signature validation, Slack request signing — so your agent only processes legitimate events.

Getting Started

If your agent is already deployed on Maritime, adding a webhook trigger takes one command. If you're building a new agent, start with the webhook handler pattern — it's the most natural way to build event-driven AI agents.

maritime trigger add --type webhook --source github --events push

Your agent is now event-driven. It sleeps until something happens, wakes up to handle it, and goes back to sleep. That's the Maritime model.