Skip to main content

Webhook Triggers

Webhook triggers let external services start an agent run by sending an HTTP POST to a unique URL. Any service that can make an HTTP request — Zapier, Make, n8n, Stripe, HubSpot, GitHub, Slack, custom scripts — can wake your agent and pass it event data.

Example use cases:

  • Deal stage changes — HubSpot notifies your agent when a deal moves to "Closed Won"
  • Payment events — Stripe triggers your agent on successful payments or refunds
  • Form submissions — Typeform or Tally webhooks kick off a follow-up workflow
  • CI/CD events — GitHub triggers your agent on PR merges or failed builds
  • Scheduled automation — Zapier or Make runs your agent on a custom schedule with enriched data

How It Works​

  1. Each agent gets a unique, secret webhook URL
  2. You paste that URL into the external service's webhook settings
  3. When the external service fires, it POSTs a JSON payload to your agent's URL
  4. MCPBundles creates a heartbeat run and passes the payload as context
  5. Your agent sees the event data and acts on it using its instructions and tools

The webhook payload is injected into the agent's prompt as Webhook Trigger Context, so the agent knows why it was triggered and what happened.

Enabling Webhooks​

  1. Go to your agent's Configuration tab
  2. Scroll to Webhook Trigger
  3. Select Webhook Enabled
  4. Click Save Configuration

Once saved, the webhook URL appears (masked by default for security). Use the Copy button to copy it without revealing it on screen.

Using the Webhook URL​

Endpoint​

POST https://mcp.mcpbundles.com/api/hooks/{your-webhook-token}

Authentication​

No headers or API keys needed. The token in the URL is the authentication — treat it like a secret.

Request Body​

Send any JSON payload. The entire body is passed to your agent as trigger context.

curl -X POST https://mcp.mcpbundles.com/api/hooks/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"event": "deal.stage_changed", "deal_id": "123", "new_stage": "Closed Won"}'

Non-JSON bodies are accepted too — they'll be stored as raw text.

Response​

StatusMeaning
202 AcceptedRun created and dispatched. Response includes run_id.
403 ForbiddenWebhook is disabled for this agent.
404 Not FoundInvalid webhook token.
409 ConflictAgent is already running (lease busy) or duplicate run.
413 Payload Too LargePayload exceeds 64 KB limit.
422 UnprocessableAgent isn't ready to run (missing config).
429 Too Many RequestsRate limited — max 5 triggers per agent per minute.

Example Response (202)​

{
  "status": "accepted",
  "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

How the Agent Sees the Payload​

When triggered by a webhook, the agent's prompt includes a Webhook Trigger Context section with the JSON payload. Your agent instructions and heartbeat checklist should describe how to handle incoming events.

Example heartbeat checklist for a webhook-triggered agent:

# Deal Event Handler

When triggered by a webhook:
1. Read the trigger context to understand what happened
2. If event is "deal.stage_changed":
   - Pull full deal details from HubSpot
   - Update the pipeline dashboard
   - Notify the team in Slack
3. If event is "deal.created":
   - Enrich the contact data
   - Score the deal
4. Summarize what actions were taken

The agent receives the full JSON payload and can act on any field. No rigid schema is required — the AI interprets the data.

Connecting External Services​

Zapier​

  1. Create a new Zap with your trigger (e.g., "New Row in Google Sheets")
  2. Add a Webhooks by Zapier action → POST
  3. Paste your agent's webhook URL
  4. Set Payload Type to JSON
  5. Map the data fields you want to send

Make (Integromat)​

  1. Create a scenario with your trigger module
  2. Add an HTTP → Make a request module
  3. Set method to POST and paste the webhook URL
  4. Set body type to JSON and map your data

n8n​

  1. Add your trigger node
  2. Add an HTTP Request node
  3. Set method to POST, paste the webhook URL
  4. Set body content type to JSON and configure the payload

Stripe​

  1. Go to Developers → Webhooks in Stripe Dashboard
  2. Click Add endpoint
  3. Paste your agent's webhook URL
  4. Select the events you want (e.g., payment_intent.succeeded)

HubSpot​

  1. Go to Settings → Integrations → Webhooks
  2. Create a new webhook subscription
  3. Paste your agent's webhook URL
  4. Select the object and event types

GitHub​

  1. Go to your repository Settings → Webhooks
  2. Click Add webhook
  3. Paste your agent's webhook URL as the Payload URL
  4. Set content type to application/json
  5. Select which events to send

Custom Scripts​

import requests

requests.post(
    "https://mcp.mcpbundles.com/api/hooks/YOUR_TOKEN",
    json={
        "source": "daily-report",
        "metrics": {"revenue": 45000, "new_users": 120},
        "generated_at": "2026-02-16T10:00:00Z",
    },
)
fetch("https://mcp.mcpbundles.com/api/hooks/YOUR_TOKEN", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    source: "daily-report",
    metrics: { revenue: 45000, new_users: 120 },
  }),
});

Security​

The Token Is the Credential​

The webhook URL contains a cryptographically random token. Anyone with the URL can trigger your agent. Treat it exactly like an API key:

  • Don't commit it to version control
  • Don't share it in public channels
  • Use environment variables in scripts
  • Rotate it if compromised

Regenerating the Token​

If your webhook URL is compromised:

  1. Go to your agent's Configuration tab
  2. In the Webhook section, click Regenerate
  3. The old URL immediately stops working
  4. Copy the new URL and update your external services

Disabling Webhooks​

To stop all webhook triggers:

  1. Toggle webhook to Disabled
  2. Click Save Configuration

The URL continues to exist but returns 403 Forbidden until re-enabled. No need to regenerate.

Rate Limiting​

Each agent is limited to 5 webhook-triggered runs per minute. Excess requests receive a 429 response with a retry_after_seconds field. This prevents runaway triggers from consuming resources.

Payload Size​

Payloads are limited to 64 KB. Requests exceeding this limit receive a 413 response. If you need to pass large data, include a reference (URL or ID) and have the agent fetch the full data using its tools.

Webhook vs Scheduled Runs​

FeatureScheduled RunsWebhook Triggers
TriggerAutomatic on intervalExternal HTTP POST
FrequencyFixed (every N minutes)On-demand
ContextPrevious run historyEvent payload + history
Best forPeriodic checksEvent-driven reactions
DeduplicationSlot-based (no duplicates)Each webhook creates a new run

You can use both on the same agent. Scheduled runs handle periodic checks while webhooks handle real-time events.

Viewing Webhook Runs​

Webhook-triggered runs appear in the History tab with a WEBHOOK trigger source badge. Click any run to see the full trigger context payload alongside the agent's response.

Troubleshooting​

Webhook Returns 404​

The token is invalid. Go to your agent's Configuration tab and copy the current webhook URL.

Webhook Returns 403​

Webhooks are disabled for this agent. Enable them in the Configuration tab and save.

Webhook Returns 422​

The agent isn't ready to run. It needs Agent Instructions, a Heartbeat Checklist, and a valid MCP source (bundle or hub) configured.

Webhook Returns 429​

You're hitting the rate limit (5 per minute per agent). Space out your triggers or batch events into a single payload.

Agent Runs But Ignores the Payload​

Update your heartbeat checklist to reference the webhook trigger context. The agent needs instructions on how to handle incoming event data — see the example above.