Maia Platform | Documentation

Event-Driven Automation

Webhooks turn Maia workflows into intelligent APIs that respond to external events — form submissions, payment notifications, chat messages, and more.

With webhooks, Maia becomes a serverless backend that processes inbound requests with AI-powered logic and returns structured responses.

How Webhooks Work

Basic Flow

Create Webhook

Deploy a workflow with webhook triggerMaia generates a unique URL:

https://hooks.modularmind.app/hooks/0nMMaZgKjmOirqosc8ohkeCuw9cV

External Event

Another system sends data to your webhook URL

curl -X POST https://webhooks.maia.app/wh_abc123xyz \
  -H "Content-Type: application/json" \
  -d '{"email": "john@example.com", "message": "Interested in demo"}'

Maia Processes

Your workflow receives the payload and executes

Parse incoming data
Run AI analysis, research, or generation
Use actions

Return Response

Maia sends back a result

{
  "status": "success",
  "lead_score": 85,
  "recommendation": "High priority - schedule demo ASAP"
}

Creating Webhook-Triggered Workflows

Simple Example: Lead Enrichment

Goal: When a contact form is submitted, enrich the lead data before adding to CRM. Workflow:

Receive form data (name, email, company)
Research company online (industry, size, funding)
Check LinkedIn for person's role
Calculate lead score (1-100)
Add to CRM with enriched data
Return lead score and priority

Deployment:

Maia provides webhook URL: https://hooks.modularmind.app/hooks/L3wKjb7iEMFTwMJFZsroWsSoc731

Usage: Your website form submits to this URL, and within minutes gets back:

{
  "lead_id": "CRM_12345",
  "score": 92,
  "priority": "hot",
  "reason": "Decision maker at Series B SaaS company"
}

Inbound Payload: Flexible Schema

Unlike traditional APIs that require strict schemas, Maia webhooks are intelligent.

Maia Understands Context

Send any data format, and Maia figures it out:

{
  "customer_email": "jane@example.com",
  "subject": "Need help with billing",
  "message": "I was charged twice this month"
}

Maia extracts:

Email: jane@example.com
Subject: Billing issue
Problem: Double charge

email=jane@example.com&subject=billing&message=charged+twice

Maia converts to structured format automatically

Content-Type: multipart/form-data

file: invoice.pdf
description: "Please process this invoice"

Maia receives file, extracts data

Content-Type: multipart/form-data

file: screenshot.png
description: "Analyze this image"

Maia detects and processes JPEG/PNG images automatically

Content-Type: multipart/form-data

file1: contract.pdf
file2: receipt.jpg
file3: notes.txt
description: "Process all these documents"

Maia handles multiple files in a single request

{
  "invoice": {
    "filename": "invoice.pdf",
    "content": "base64EncodedData...",
    "encoding": "base64"
  },
  "supporting_docs": [
    {
      "filename": "receipt.jpg",
      "data": "binaryData..."
    }
  ]
}

Maia processes files embedded in JSON (base64 or raw binary)

Content-Type: multipart/form-data

file: documents.zip
instructions: "Extract and analyze all contents"

Maia automatically extracts ZIP files and processes contents (PDFs, images, text files)

{
  "order_id": "12345",
  "customer": {
    "name": "John Doe",
    "contact": {
      "email": "john@example.com"
    }
  },
  "items": [
    {"product": "Widget", "qty": 5}
  ],
  "attachments": {
    "receipt": "base64Data..."
  }
}

Maia understands arbitrary nested JSON structures

Outbound Response: Controlling What Gets Returned

When deploying a webhook, you choose how Maia responds to incoming requests.

Default Response (Immediate)

If you don’t enable “Respond to webhook with data”, Maia returns immediately with one of these standard responses: Success:

{
  "type": "success",
  "message": "Workflow execution triggered successfully."
}

Error (Invalid Endpoint):

{
  "type": "error",
  "code": "invalid_endpoint",
  "message": "Invalid endpoint. Please check the path and try again."
}

Error (Disabled Endpoint):

{
  "type": "error",
  "code": "endpoint_disabled",
  "message": "This endpoint is currently disabled."
}

The workflow executes asynchronously, but the caller doesn’t wait for results.

Custom Data Response

Enable “Respond to webhook with data” to return workflow outputs back to the caller.

When enabled, you define Body Parameters — exactly like configuring Custom Actions. This tells Maia what data to include in the response.

Supported Response Types

Maia can return:

Text data in JSON format (structured responses)
Images (JPEG, PNG)
Text files
PDFs
ZIP files

Data, including files, can be generated throughout the workflow or downloaded from external sources.

Defining Response Parameters

For each parameter you want to return, specify: Name: The field name in the response (e.g., lead_score, generated_image, report_pdf) Description: Natural language explanation of what this field contains and where Maia should get the value from. This helps Maia understand which workflow outputs map to this response field. Type: The type of data (text, file, etc.)

Response parameter definitions work identically to body parameters in Custom Actions. See that section for detailed parameter configuration guidance.

Example: Lead Scoring Response

Configuration:

Body Parameters:
- Name: lead_id
  Description: The CRM record ID assigned to this lead

- Name: score
  Description: Calculated lead score from 1-100 based on company research

- Name: priority
  Description: Priority level (hot/warm/cold) based on the score

- Name: next_action
  Description: Recommended follow-up action for the sales team

Returned Response:

{
  "lead_id": "CRM_54321",
  "score": 88,
  "priority": "hot",
  "next_action": "Schedule demo within 24 hours"
}

Example: Document Generation Response

Configuration:

Body Parameters:
- Name: report_pdf
  Description: The generated PDF report file created by the workflow
  Type: File (base64)

- Name: summary
  Description: Brief text summary of the report contents

Returned Response:

{
  "report_pdf": "base64EncodedPdfData...",
  "summary": "Q4 2025 Sales Report - 23% growth, top performer: Enterprise segment"
}

Real-World Webhook Examples

Example 1: Intelligent Chatbot Backend

Setup: Website chat widget → Maia webhook Workflow:

Receive visitor message
Search knowledge base using custom action
If found: Generate helpful response
If not found: Create support ticket via custom action, send notification
Return response to chat widget

Request from caller:

{
  "visitor_id": "vis_123",
  "message": "What's your refund policy?",
  "page_url": "/pricing"
}

Response to caller:

{
  "response": "We offer a 30-day money-back guarantee on all 
               plans. If you're not satisfied, contact 
               support@company.com for a full refund.",
  "confidence": 0.92,
  "escalate": false,
  "source": "Help Center: Refund Policy"
}

Result: Instant, accurate responses powered by AI, with human fallback.

Example 2: Invoice Processing

Setup: Email automation → Maia webhook Workflow:

Receive invoice PDF as attachment
Extract data (vendor, amount, due date, line items)
Validate against purchase order using custom action
Add to accounting system via custom action
If > $5000, create approval request via custom action
Return processing summary

Request from caller:

{
  "from": "vendor@supplier.com",
  "subject": "Invoice #12345",
  "attachment_url": "https://storage.../invoice.pdf"
}

Response to caller:

{
  "status": "processed",
  "invoice_number": "12345",
  "vendor": "ABC Supplier",
  "amount": 3250.00,
  "due_date": "2026-01-15",
  "accounting_id": "INV_789",
  "approval_required": false,
  "line_items": [
    {"description": "Widget A", "quantity": 100, "price": 25.00},
    {"description": "Widget B", "quantity": 50, "price": 15.00}
  ]
}

Result: Automated invoice processing with data extraction and validation.

Example 3: Product Review Aggregator

Setup: Product review form → Maia webhook Workflow:

Receive review text and rating
Analyze sentiment (positive/negative/neutral)
Extract key themes (quality, pricing, support, etc.)
Check for spam/fake reviews
If legitimate, publish to website via custom action
If mentions bug/issue, create support ticket via custom action
Return analysis

Request from caller:

{
  "product_id": "prod_456",
  "rating": 4,
  "review": "Great product! Works as advertised. Customer 
             support was responsive when I had a question 
             about setup. Only issue: shipping took longer 
             than expected.",
  "reviewer_email": "customer@example.com"
}

Response to caller:

{
  "approved": true,
  "spam_score": 0.05,
  "sentiment": "positive",
  "themes": {
    "product_quality": "positive",
    "customer_support": "positive",
    "shipping_speed": "negative"
  },
  "action_items": [
    {
      "type": "feedback",
      "category": "shipping",
      "message": "Customer experienced slow shipping"
    }
  ],
  "published_url": "https://site.com/reviews/rev_123"
}

Result: Intelligent review moderation with actionable insights.

Next: Security & Privacy

Learn how Maia protects your data and credentials

Introduction

Planning & Building Workflows

Maia's Capabilities

Connections & Actions

Deployment & Automation

Security & FAQ

Webhooks: Maia as a Backend

Event-Driven Automation

How Webhooks Work

Basic Flow

Creating Webhook-Triggered Workflows

Simple Example: Lead Enrichment

Inbound Payload: Flexible Schema

Maia Understands Context

Outbound Response: Controlling What Gets Returned

Default Response (Immediate)

Custom Data Response

Supported Response Types

Defining Response Parameters

Example: Lead Scoring Response

Example: Document Generation Response

Real-World Webhook Examples

Example 1: Intelligent Chatbot Backend

Example 2: Invoice Processing

Example 3: Product Review Aggregator

Next: Security & Privacy

Introduction

Planning & Building Workflows

Maia's Capabilities

Connections & Actions

Deployment & Automation

Security & FAQ

​Event-Driven Automation

​How Webhooks Work

​Basic Flow

​Creating Webhook-Triggered Workflows

​Simple Example: Lead Enrichment

​Inbound Payload: Flexible Schema

​Maia Understands Context

​Outbound Response: Controlling What Gets Returned

​Default Response (Immediate)

​Custom Data Response

​Supported Response Types

​Defining Response Parameters

​Example: Lead Scoring Response

​Example: Document Generation Response

​Real-World Webhook Examples

​Example 1: Intelligent Chatbot Backend

​Example 2: Invoice Processing

​Example 3: Product Review Aggregator

Next: Security & Privacy

Event-Driven Automation

How Webhooks Work

Basic Flow

Creating Webhook-Triggered Workflows

Simple Example: Lead Enrichment

Inbound Payload: Flexible Schema

Maia Understands Context

Outbound Response: Controlling What Gets Returned

Default Response (Immediate)

Custom Data Response

Supported Response Types

Defining Response Parameters

Example: Lead Scoring Response

Example: Document Generation Response

Real-World Webhook Examples

Example 1: Intelligent Chatbot Backend

Example 2: Invoice Processing

Example 3: Product Review Aggregator