Smart Webhooks

Smart Webhooks are AI-powered webhook processors. They receive incoming webhook events from any source — GitHub, Stripe, Shopify, or your own services — and process them with plain-English instructions backed by MCP tools.

Instead of writing webhook handler code, you write instructions like “When a new issue is created, label it based on content. If it’s a bug, assign to the on-call team.” The AI agent reads the webhook payload, follows your instructions, and uses your connected MCP tools to take action.

How It Works

External Service sends a webhook event
    → Aerostack verifies the signature (if configured)
    → Filters by event type
    → AI agent reads the payload and follows your instructions
    → Agent uses MCP tools to take action
    → Returns { ok: true, actions_taken, cost_cents }

Key Design Principles

Secure by Default

Smart Webhooks always return { ok: true } with HTTP 200 for all requests, whether processed or not. This is a security measure — to verify your webhook is actually being processed, check the run history in the dashboard or via GET /api/smart-webhooks/:id/runs.

Plain English Instructions

The instructions field is the core of a Smart Webhook. It tells the AI what to do when a webhook arrives. Write it like you would explain the task to a capable colleague:

When a payment fails in Stripe:
1. Look up the customer in our database
2. Send them a notification via the messaging tool
3. If this is the 3rd failed attempt, flag the account for review
4. Log the event with the payment amount and failure reason

The AI agent receives the full webhook payload along with your instructions and has access to all tools in your MCP workspace.

MCP Tool Access

Every Smart Webhook connects to an MCP workspace. The tools available in that workspace determine what actions the AI can take. Common setups:

Use Cases

Auto-Triage GitHub Issues — When a new issue is created, the AI reads the title and body, classifies it (bug, feature request, question), applies the appropriate labels, and assigns it to the right team. If it matches a known pattern, it can even post a suggested fix.

Process Stripe Payment Events — On payment success, update the customer record and send a confirmation. On payment failure, notify the customer and flag the account. On subscription changes, update access levels in your database.

Sync CRM Data — When a form submission arrives, the AI extracts contact details, checks for duplicates in your CRM via MCP tools, and creates or updates the contact record. It can also trigger follow-up workflows based on the submission content.

Monitor Deployments — Receive deployment webhooks from your CI/CD system. The AI checks if the deployment succeeded, runs a quick health check via an HTTP tool, and posts a summary to your team’s Slack channel.

Content Moderation — When new content is submitted via webhook, the AI analyzes it for policy violations and takes appropriate action — approve, flag for review, or reject with a reason.

Source Types

The source_type field is informational and helps organize your webhooks in the dashboard:

LLM Configuration

Smart Webhooks use a fixed LLM configuration optimized for reliability:

The system prompt is automatically set to:

You are a webhook processor. You receive webhook events and take actions based on plain English instructions. Use the available MCP tools to perform actions. Be precise and only do what the instructions say.

Your instructions are appended to the webhook payload that the AI receives.

Comparing Agent Endpoints vs Smart Webhooks

Rate Limits

Exceeding the rate limit returns { ok: true } silently. The webhook source sees a successful delivery but no processing occurs.

Quick Example

# Receive a GitHub issue webhook and auto-triage it
curl -X POST https://api.aerostack.dev/api/webhooks/smart/github-triage \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: sha256=abc123..." \
  -d '{
    "action": "opened",
    "issue": {
      "title": "Login page returns 500 error",
      "body": "When I try to log in with my email, the page shows a 500 error...",
      "number": 42
    },
    "repository": {
      "full_name": "acme/api"
    }
  }'

Response:

{
  "ok": true,
  "actions_taken": "Labeled issue #42 as 'bug' and 'priority:high'. Assigned to @oncall-team. Posted a comment acknowledging the report.",
  "tool_calls": 3,
  "cost_cents": 0.45
}

Next Steps

• Quick Start — Create your first Smart Webhook in 3 minutes
• HMAC Verification — Secure your webhooks with signature verification
• Event Filtering — Process only the events you care about
• API Reference — Full endpoint documentation