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"
}

Chat2Desk Status Events (Auto-resume)

Chat2Desk also delivers status events to the same webhook URL when a human operator acts on a dialog. AIAgentCore consumes these events to keep the AI session in sync — for example automatically closing the session when the operator closes the ticket.

The event type is determined by the hook_type field on the inbound payload (verbatim — not event or type).

Status payload schema (flat, snake_case):

{
  "hook_type": "close_dialog",
  "request_id": 12345,
  "dialog_id": 67890
}

• hook_type — required, determines the action
• request_id — required (number)
• dialog_id — optional on close_* events, present on transfers

hook_type → internal action:

hook_type	Internal action	Effect on AIAgentCore session
close_dialog	session_close	Session moves to closed
close_request	session_close	Session moves to closed
dialog_transferred	session_transfer_external	Session stays paused, transfer is recorded in the Shared Conversation Context

No extra configuration is needed on the AIAgentCore side — the webhook just has to be registered (see Register-webhook helper below).

See Session Lifecycle for the full state machine.

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")
  );
}

Register-webhook helper (UI + API)

You don't have to copy and paste the webhook URL into the Chat2Desk dashboard by hand — AIAgentCore can register (or re-register) the webhook on your behalf.

UI: In Settings → Integrations, open the card for your Chat2Desk integration. The card shows a Register webhook button (or Re-register webhook if one is already registered) plus a Webhook OK / Webhook pendente badge. Clicking the button calls the helper endpoint below.

API:

POST /api/integrations/:id/register-webhook

See the API Reference for the full schema. The call is idempotent — it creates a new registration if none exists, or updates the existing one. On success it returns:

{
  "ok": true,
  "webhookRegisteredAt": "2026-05-21T17:45:12Z"
}

Prerequisite: the integration must have its apiUrl field configured (Chat2Desk has separate global and Europe instances; pick the one matching your account). Without apiUrl the call returns 400 not_supported.

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