Webhooks

AIAgentCore receives inbound messages from messaging platforms via webhooks. When a customer sends a message on WhatsApp, Telegram, or any connected channel, the platform delivers it to your webhook endpoint for processing.

Webhook URL Format

POST https://api.aiagentcore.com/api/webhook/{connectorType}/{integrationId}

Parameter	Description	Example
connectorType	The messaging platform connector	chat2desk, webchat
integrationId	Your integration ID (from Dashboard)	42

Example:

https://api.aiagentcore.com/api/webhook/chat2desk/42

Supported Connectors

Chat2Desk

Chat2Desk is a multi-channel messaging platform that aggregates WhatsApp, Telegram, Instagram, VK, and more into a single API.

Setup:

1. Create a Chat2Desk integration in the AIAgentCore Dashboard
2. Copy the webhook URL
3. In your Chat2Desk dashboard, set the webhook URL to:

   https://api.aiagentcore.com/api/webhook/chat2desk/{integrationId}

4. Configure the webhook secret for signature verification

Inbound payload (sent by Chat2Desk):

{
  "text": "Hello, I need help with my order",
  "client_id": "12345678",
  "channel_id": "987654",
  "transport": "whatsapp"
}

Webchat

The webchat connector uses WebSocket (Socket.IO) instead of HTTP webhooks. Messages from the embedded widget are delivered in real-time via a persistent connection.

See Widget Embed for setup instructions.

Webhook Signature Verification

AIAgentCore verifies the authenticity of incoming webhooks using HMAC-SHA256 signatures.

How It Works

1. The sending platform computes an HMAC-SHA256 hash of the request body using the shared webhook secret
2. The hash is sent in the x-webhook-signature or x-hub-signature-256 header
3. AIAgentCore recomputes the hash and compares it using timing-safe comparison

Signature Header Format

x-webhook-signature: sha256=a1b2c3d4e5f6...

Or alternatively:

x-hub-signature-256: sha256=a1b2c3d4e5f6...

Verification Example (Node.js)

If you need to send test webhooks or verify the signature yourself:

import { createHmac, timingSafeEqual } from "crypto";

function verifySignature(
  body: string,
  signature: string,
  secret: string
): boolean {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex");

  const received = signature.replace("sha256=", "");

  return timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(received, "hex")
  );
}

Processing Flow

When a webhook is received, AIAgentCore processes it asynchronously:

Platform → Webhook Endpoint → Signature Verification → Message Parsing → Queue → AI Agent → Response

1. Receive — The webhook endpoint accepts the HTTP POST
2. Verify — HMAC signature is validated (401 if invalid)
3. Parse — The connector normalizes the platform-specific payload into a standard message format
4. Enqueue — The message is queued for async processing
5. Process — The AI agent generates a response using the configured LLM and knowledge base
6. Reply — The response is sent back through the same messaging channel

Response Codes

Status	Description
200	Webhook received and processed (or ignored)
401	Invalid webhook signature
403	Integration is not active
404	Unknown connector type or integration not found
500	Internal server error

Success response:

{
  "ok": true
}

Endpoint Verification

Some platforms send a GET request to verify the webhook URL. AIAgentCore handles this automatically:

GET https://api.aiagentcore.com/api/webhook/{connectorType}/{integrationId}

Response (200 OK):

{
  "ok": true,
  "verified": true
}

Best Practices

• Always configure a webhook secret — Without it, anyone could send fake messages to your integration
• Use HTTPS — The production API enforces HTTPS for all webhook endpoints
• Monitor webhook logs — Check the Dashboard for delivery status and errors
• Integration must be active — Inactive integrations reject webhooks with 403