Capabilities & Webhooks

Configure native business actions that AI agents can execute on behalf of your customers.

Capabilities vs Connectors

Configure capabilities in your Business Dashboard.

Public vs Private Capabilities

Each capability can be configured as public or private, controlling who can execute the action.

Public Capabilities

Public capabilities can be executed by any authenticated user. These are your customer-facing actions that anyone should be able to use.

Private Capabilities

Private capabilities are restricted to members of your organization. Use these for internal tools that should not be accessible to the public.

How Authentication Works

When executing any capability (public or private), the flow is:

1. User asks AI agent to perform an action (e.g., "Book a table")
2. AI agent calls execute_action via MCP
3. If not authenticated, MCP client prompts user to sign in via Dock AI OAuth
4. User authenticates with email (6-digit OTP, no password)
5. For private capabilities: system checks organization membership
6. Action executes with user's verified email in webhook payload

Configuring Visibility

Set the visibility of each capability in your Business Dashboard. Toggle the "Private (org members only)" switch to restrict access to your team.

Standard Actions

Dock AI provides 6 standard action types with pre-configured schemas. Using standard slugs improves AI understanding and discoverability.

send_message - Contact

Allow customers to send messages to your team.

book - Booking

Allow bookings for tables, appointments, or services.

search_catalog - Catalog

Allow searching through your products or services.

get_availability - Availability

Show available time slots.

request_quote - Quote

Allow quote requests from customers.

subscribe - Newsletter

Allow newsletter subscriptions for news and offers.

Custom Webhooks

Create custom capabilities with your own webhook endpoints. This gives you full control over the action execution.

Slug Naming Conventions

Custom slugs must follow these rules:

• Start with a lowercase letter: a-z
• Contain only lowercase letters, numbers, and underscores: a-z0-9_
• Maximum 50 characters
• Pattern: /^[a-z][a-z0-9_]*$/

AI Description Best Practices

Write clear descriptions that help AI agents understand when to use this action:

• Start with "Use this action to..."
• Explain what the action does and what it returns
• Include any constraints (hours, limits, requirements)
• Keep it under 200 characters

Webhook URL Requirements

• HTTPS required - HTTP URLs are rejected
• No private IPs - 127.x.x.x, 10.x.x.x, 192.168.x.x, 172.16-31.x.x blocked
• No localhost - localhost and ::1 blocked
• Domain names only - Raw IP addresses rejected
• Blocked ports: 22 (SSH), 23 (Telnet), 25 (SMTP), 3306 (MySQL), 5432 (PostgreSQL), 6379 (Redis), 27017 (MongoDB)

Input Fields Configuration

Configure the data your webhook will receive using the visual form editor in your Business Dashboard. For each field, you can set:

• Field key - Technical name (lowercase, underscores only)
• Label - Display name shown to the AI
• Type - Text, Number, or Yes/No
• Format - Email, Date, Time, Phone (for validation)
• Required - Toggle on/off

{
  "date": {
    "type": "string",
    "format": "date",
    "required": true,
    "label": "Date",
    "placeholder": "YYYY-MM-DD"
  },
  "time": {
    "type": "string",
    "format": "time",
    "required": true,
    "label": "Time",
    "placeholder": "HH:MM"
  },
  "guests": {
    "type": "number",
    "required": true,
    "label": "Number of guests",
    "min": 1,
    "max": 20
  },
  "name": {
    "type": "string",
    "required": true,
    "label": "Name",
    "placeholder": "Name for the booking",
    "maxLength": 100
  },
  "phone": {
    "type": "string",
    "format": "phone",
    "required": false,
    "label": "Phone",
    "placeholder": "+1 555 123 4567"
  },
  "notes": {
    "type": "string",
    "required": false,
    "label": "Notes",
    "placeholder": "Allergies, special occasion...",
    "maxLength": 500
  }
}

Field Types

String Formats

Field Properties

Payload & Security

Webhook Payload

When an action is executed, Dock AI sends a POST request to your webhook URL with the following payload:

{
  "execution_id": "550e8400-e29b-41d4-a716-446655440000",
  "action": "book",
  "params": {
    "date": "2025-02-15",
    "time": "20:00",
    "guests": 4,
    "name": "Jean Dupont",
    "phone": "+33612345678"
  },
  "user_email": "user@example.com",
  "timestamp": "2025-01-17T12:00:00.000Z"
}

Request Headers

Authentication

Configure an Authorization header in your capability settings. Dock AI will include this header in every request to your endpoint.

Response Requirements

Prompt Injection Protection

Webhook responses are scanned for prompt injection attempts. If suspicious content is detected, the response is blocked and a security warning is returned to the AI agent.

Blocked Field Names

Integration Examples

Make (Integromat)

Zapier

n8n

Express.js Webhook

const express = require('express');
const app = express();

app.use(express.json());

app.post('/api/dockai/book', (req, res) => {
  // Verify Authorization header
  const authHeader = req.headers['authorization'];
  if (authHeader !== `Bearer ${process.env.DOCKAI_API_KEY}`) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  const { execution_id, action, params, user_email, timestamp } = req.body;

  // Process booking
  const { date, time, guests, name, phone } = params;

  // Your booking logic here...
  const booking = createBooking({ date, time, guests, name, phone, email: user_email });

  // Return confirmation
  res.json({
    success: true,
    confirmation: `Booking confirmed for ${guests} guests on ${date} at ${time}`,
    reference: booking.id
  });
});

app.listen(3000);

FastAPI Webhook

from fastapi import FastAPI, Request, HTTPException
from pydantic import BaseModel
from typing import Dict, Any
import os

app = FastAPI()

class WebhookPayload(BaseModel):
    execution_id: str
    action: str
    params: Dict[str, Any]
    user_email: str
    timestamp: str

@app.post("/api/dockai/book")
async def handle_booking(request: Request, payload: WebhookPayload):
    # Verify Authorization header
    auth_header = request.headers.get("authorization")
    if auth_header != f"Bearer {os.environ['DOCKAI_API_KEY']}":
        raise HTTPException(status_code=401, detail="Unauthorized")

    # Extract booking params
    date = payload.params.get("date")
    time = payload.params.get("time")
    guests = payload.params.get("guests")
    name = payload.params.get("name")

    # Your booking logic here...
    booking = create_booking(date=date, time=time, guests=guests, name=name)

    return {
        "success": True,
        "confirmation": f"Booking confirmed for {guests} guests on {date} at {time}",
        "reference": booking.id
    }

Rate Limiting

Each capability has its own rate limit to prevent abuse. Limits are tracked per user (hashed user ID for privacy).

Configure rate limits in your Business Dashboard under each capability's settings.

Troubleshooting