Webhook Tools Guide

This guide explains the webhook integration tools available in ChimerAI and how to install them via the CLI.

ChimerAI has two distinct webhook concepts:

1. Incoming webhooks - receiving events from Stripe (part of chimerai add billing)
2. Outgoing webhook tools - the AI agent calling external services like n8n, Zapier, Make, Slack

Outgoing Webhooks: AI Agent Tool

Installation

chimerai add ai-service
chimerai add ai-tools webhook_tools

The webhook tool is part of the AI service layer (Python). It gives the AI agent the ability to call any HTTP endpoint as part of an automated workflow.

Files installed:

services/ai/services/tools/webhook_tools.py

No additional Python dependencies - uses httpx which is already included in the AI service core.

WebhookTools Class

The WebhookTools class is available to the AI agent as a callable tool. It supports any HTTP method and integrates natively with the most common automation platforms.

call_webhook(url, payload, method, headers, query_params, auth_token)

Universal HTTP caller. Sends a request to any URL with optional JSON body, custom headers, query parameters and Bearer token authentication.

result = await webhook_tools.call_webhook(
    url="https://myapp.com/api/notify",
    payload={"event": "order_placed", "orderId": "123"},
    method="POST",
    auth_token="my-secret-token"
)
# result: { "success": True, "status_code": 200, "response": {...} }

Returns:

{
  "success": bool,
  "status_code": int,
  "response": dict,  # parsed JSON or {"text": "..."}
  "url": str,
  "method": str
}

On timeout (>30s) or network error, returns {"error": "...", "url": "..."} without raising an exception.

call_n8n_webhook(webhook_id, payload, n8n_url?)

Calls an n8n webhook by ID. The base URL defaults to the N8N_WEBHOOK_URL environment variable.

result = await webhook_tools.call_n8n_webhook(
    webhook_id="my-workflow-id",
    payload={"user": "Alice", "action": "signup"}
)

Set N8N_WEBHOOK_URL in your environment or pass it directly:

N8N_WEBHOOK_URL=https://n8n.mycompany.com

call_zapier_webhook(hook_id, payload)

Calls a Zapier Catch Hook. The hook_id is the last segment of the Zapier webhook URL.

result = await webhook_tools.call_zapier_webhook(
    hook_id="abc123/xyz456",
    payload={"name": "Alice", "email": "alice@example.com"}
)

call_make_webhook(webhook_path, payload, region?)

Calls a Make.com (formerly Integromat) webhook. Region defaults to eu1.

result = await webhook_tools.call_make_webhook(
    webhook_path="abc123def456",
    payload={"trigger": "new_user"},
    region="us1"
)

notify_slack_via_webhook(webhook_url, message, channel?, username?, icon_emoji?)

Sends a message to a Slack channel via an Incoming Webhook URL.

result = await webhook_tools.notify_slack_via_webhook(
    webhook_url="https://hooks.slack.com/services/T.../B.../xxx",
    message="New signup: Alice (alice@example.com)",
    channel="#alerts",
    username="ChimerAI Bot",
    icon_emoji=":robot_face:"
)

Incoming Webhooks: Stripe

The Stripe webhook handler (app/api/webhooks/stripe/route.ts) is installed as part of chimerai add billing. See the Billing Guide for details.

Handled Stripe Events

Registering the Webhook Endpoint

In the Stripe Dashboard, go to Developers -> Webhooks -> Add endpoint:

• URL: https://yourdomain.com/api/webhooks/stripe
• Events: Select the events listed above

Copy the Signing secret (whsec_...) and add it to your .env:

STRIPE_WEBHOOK_SECRET=whsec_...

For local development with the Stripe CLI:

stripe listen --forward-to localhost:3000/api/webhooks/stripe

The CLI prints a temporary signing secret that you can use locally.

Custom Incoming Webhook

To receive webhooks from other services (GitHub, Shopify, etc.), create a custom route handler:

// app/api/webhooks/github/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const signature = request.headers.get('x-hub-signature-256');
  const body = await request.text();

  // Verify signature here...

  const event = JSON.parse(body);
  if (event.action === 'opened' && event.pull_request) {
    // Handle PR opened event
  }

  return NextResponse.json({ received: true });
}

Notes

• The WebhookTools class uses httpx.AsyncClient with a 30-second timeout. This is appropriate for automation workflows but may be too slow for real-time user-facing requests.
• All methods return a result dict instead of raising exceptions on HTTP errors, making them safe to use in AI agent loops.
• The User-Agent header is set to ChimerAI-Agent/1.0 on all outgoing requests.
• For Slack, use Incoming Webhooks (not the Slack API). Create one at https://api.slack.com/apps under your app's "Incoming Webhooks" section.