Webhooks API

Webhooks let external systems send messages to your agent and receive AI-generated responses. Create a webhook to get a unique token URL, then POST messages to it from any system (Zapier, n8n, custom apps).

How it works

1. Create a webhook for your agent (returns a unique token)

2. POST messages to /api/webhook/<token>

3. The agent processes the message and returns a response

4. Credits are charged to the agent owner's account

POST/agents/:agent_id/webhooks

Create a webhook for an agent. Requires agent-scoped or global API key.

Request Body

JSON

{
  "name": "Zapier Integration",
  "outgoing_url": "https://hooks.example.com/callback"
}

Response

JSON

{
  "id": "wh_abc123",
  "agent_id": "agent-uuid",
  "name": "Zapier Integration",
  "token": "whk_xxxxxxxxxxxxxxxxxxxxx",
  "webhook_url": "https://ai-teammate.net/api/webhook/whk_xxxxxxxxxxxxxxxxxxxxx",
  "is_active": true,
  "created_at": "2026-04-14T12:00:00Z"
}

Save the token — it won't be shown again in full.

POST/webhook/:tokenPublic

Send a message to the agent via webhook. No authentication needed — the token is the auth.

Request Body

JSON

{
  "message": "Summarize today's sales report",
  "user_id": "external-user-123"
}

Response

JSON

{
  "response": "Based on today's data, total sales reached $12,500...",
  "conversation_id": "conv-uuid",
  "credits_used": 3
}

cURL Example

bash

curl -X POST https://ai-teammate.net/api/webhook/whk_YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello from my app!"}'

GET/agents/:agent_id/webhooks

List all webhooks for an agent.

JSON

[
  {
    "id": "wh_abc123",
    "name": "Zapier Integration",
    "token_prefix": "whk_xxxx...",
    "is_active": true,
    "created_at": "2026-04-14T12:00:00Z",
    "last_used_at": "2026-04-14T15:30:00Z"
  }
]

Management Endpoints

PATCH/webhooks/:idUpdate webhook name, outgoing URL, or active status

DELETE/webhooks/:idDelete a webhook

POST/webhooks/:id/regenerateRegenerate webhook token (invalidates old token)

Integration Examples

Node.js / Express

JavaScript

const express = require('express');
const app = express();
app.use(express.json());

const WEBHOOK_URL = 'https://ai-teammate.net/api/webhook/whk_YOUR_TOKEN';

app.post('/ask-ai', async (req, res) => {
  const response = await fetch(WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: req.body.question }),
  });
  const data = await response.json();
  res.json({ answer: data.response });
});

Python / Flask

Python

import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_URL = "https://ai-teammate.net/api/webhook/whk_YOUR_TOKEN"

@app.route("/ask-ai", methods=["POST"])
def ask_ai():
    data = request.json
    resp = requests.post(WEBHOOK_URL, json={"message": data["question"]})
    return jsonify({"answer": resp.json()["response"]})

n8n / Zapier

n8n: Use HTTP Request node → POST to webhook URL → parse response.response

Zapier: Use Webhooks by Zapier (POST) → set URL to webhook URL → map response

Error Codes

Code	Meaning	Action
400	Missing message field	Include "message" in request body
402	Insufficient credits	Top up agent owner credits
404	Invalid token	Check webhook token is correct
429	Rate limited	Wait 60s, max 10 req/min
500	Server error	Retry with backoff

Rate Limits & Credits

Webhook calls are rate-limited to 10 requests/minute per webhook.

Each call consumes credits from the agent owner's balance.

Credit formula: (input_tokens + output_tokens * 3) / 100 (min 1)

If the owner has no credits, the webhook returns 402 Payment Required.

Webhooks API

How it works

1. Create a webhook for your agent (returns a unique token)

2. POST messages to /api/webhook/<token>

3. The agent processes the message and returns a response

4. Credits are charged to the agent owner's account

POST/agents/:agent_id/webhooks

Create a webhook for an agent. Requires agent-scoped or global API key.

Request Body

JSON

{
  "name": "Zapier Integration",
  "outgoing_url": "https://hooks.example.com/callback"
}

Response

JSON

{
  "id": "wh_abc123",
  "agent_id": "agent-uuid",
  "name": "Zapier Integration",
  "token": "whk_xxxxxxxxxxxxxxxxxxxxx",
  "webhook_url": "https://ai-teammate.net/api/webhook/whk_xxxxxxxxxxxxxxxxxxxxx",
  "is_active": true,
  "created_at": "2026-04-14T12:00:00Z"
}

Save the token — it won't be shown again in full.

POST/webhook/:tokenPublic

Send a message to the agent via webhook. No authentication needed — the token is the auth.

Request Body

JSON

{
  "message": "Summarize today's sales report",
  "user_id": "external-user-123"
}

Response

JSON

{
  "response": "Based on today's data, total sales reached $12,500...",
  "conversation_id": "conv-uuid",
  "credits_used": 3
}

cURL Example

bash

curl -X POST https://ai-teammate.net/api/webhook/whk_YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello from my app!"}'

GET/agents/:agent_id/webhooks

List all webhooks for an agent.

JSON

[
  {
    "id": "wh_abc123",
    "name": "Zapier Integration",
    "token_prefix": "whk_xxxx...",
    "is_active": true,
    "created_at": "2026-04-14T12:00:00Z",
    "last_used_at": "2026-04-14T15:30:00Z"
  }
]

Management Endpoints

PATCH/webhooks/:idUpdate webhook name, outgoing URL, or active status

DELETE/webhooks/:idDelete a webhook

POST/webhooks/:id/regenerateRegenerate webhook token (invalidates old token)

Integration Examples

Node.js / Express

JavaScript

const express = require('express');
const app = express();
app.use(express.json());

const WEBHOOK_URL = 'https://ai-teammate.net/api/webhook/whk_YOUR_TOKEN';

app.post('/ask-ai', async (req, res) => {
  const response = await fetch(WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: req.body.question }),
  });
  const data = await response.json();
  res.json({ answer: data.response });
});

Python / Flask

Python

import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_URL = "https://ai-teammate.net/api/webhook/whk_YOUR_TOKEN"

@app.route("/ask-ai", methods=["POST"])
def ask_ai():
    data = request.json
    resp = requests.post(WEBHOOK_URL, json={"message": data["question"]})
    return jsonify({"answer": resp.json()["response"]})

n8n / Zapier

n8n: Use HTTP Request node → POST to webhook URL → parse response.response

Zapier: Use Webhooks by Zapier (POST) → set URL to webhook URL → map response

Error Codes

Code	Meaning	Action
400	Missing message field	Include "message" in request body
402	Insufficient credits	Top up agent owner credits
404	Invalid token	Check webhook token is correct
429	Rate limited	Wait 60s, max 10 req/min
500	Server error	Retry with backoff

Rate Limits & Credits

Webhook calls are rate-limited to 10 requests/minute per webhook.

Each call consumes credits from the agent owner's balance.

Credit formula: (input_tokens + output_tokens * 3) / 100 (min 1)

If the owner has no credits, the webhook returns 402 Payment Required.

Webhooks API

How it works

Request Body

Response

Request Body

Response

cURL Example

Management Endpoints

Integration Examples

Node.js / Express

Python / Flask

n8n / Zapier

Error Codes

Rate Limits & Credits

AI Teammate

Webhooks API

How it works

Request Body

Response

Request Body

Response

cURL Example

Management Endpoints

Integration Examples

Node.js / Express

Python / Flask

n8n / Zapier

Error Codes

Rate Limits & Credits