Human Agent Webhook

Receive HTTP POST callbacks when human agents respond to user messages. Perfect for logging, analytics, CRM integration, and custom notification systems.

HTTP Request (Incoming)

POST (Your Webhook URL)

When is This Triggered?

This webhook is triggered whenever a human agent sends a reply in any conversation, regardless of whether the conversation was started via API or chat widget.

Webhooks are only sent if your agent has a webhook URL configured in settings.

Request Headers

Header	Value	Description
Content-Type	application/json	Always JSON payload
User-Agent	Aksita-Webhook/1.0	Identifies Aksita webhook
X-Webhook-Signature	HMAC-SHA256 hex	Signature for verification (optional - only if webhook secret configured)

Payload Structure

Field	Type	Description
response	array	Human agent message (array of strings)
conversation_id	string	Unique conversation identifier
message_id	string	Message ID for this reply
credits	number	Always 0 (human agent responses are free)
remaining_credits	number	User's remaining credits after this conversation
additional_context	string	Additional context (empty string if not set)
source	string	Always "human_agent" to identify webhook source
timestamp	string	ISO 8601 timestamp (RFC3339)

Example Payload

{
  "response": ["hello"],
  "message_id": "2125",
  "conversation_id": "2a73ddbe-31cd-4a60-83ff-1fc2a1627ccc",
  "credits": 0,
  "remaining_credits": 1234,
  "additional_context": "",
  "source": "human_agent",
  "timestamp": "2026-01-22T15:18:18+07:00"
}

Implementation Examples

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

// IMPORTANT: Use express.raw() to get raw body for signature verification
app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const webhookSecret = process.env.WEBHOOK_SECRET; // From agent settings
  
  // Verify signature if provided
  if (signature && webhookSecret) {
    const hmac = crypto.createHmac('sha256', webhookSecret);
    hmac.update(req.body); // Raw body as buffer
    const calculatedSignature = hmac.digest('hex');
    
    if (calculatedSignature !== signature) {
      return res.status(400).json({ error: 'Invalid signature' });
    }
  }
  
  // Parse and process webhook
  const payload = JSON.parse(req.body);
  console.log('Human agent replied:', payload.response[0]);
  console.log('Conversation ID:', payload.conversation_id);
  console.log('Source:', payload.source); // "human_agent"
  
  // Respond with 200 OK
  res.json({ received: true });
});

app.listen(3000);

Signature Verification (Optional but Recommended)

If you configure a webhook secret in your agent settings, the X-Webhook-Signature header will be sent with all webhooks. We strongly recommend verifying this signature to ensure the webhook is authentic and prevent malicious requests.

Expected Response

Successful webhook receipt (any 2xx status)

200 OK

{
  "received": true
}

Any HTTP status code between 200-299 is considered successful. Response body is optional.

Technical Details

Signature Algorithm	HMAC-SHA256 (hex)
Timeout	10 seconds
Retry Policy	No automatic retries
Success Status	HTTP 200-299
User-Agent	Aksita-Webhook/1.0

Important:

Webhooks are sent asynchronously from a queue
Failed webhooks are NOT automatically retried
Your endpoint must respond within 10 seconds
Signature verification is optional but strongly recommended

Webhook Flow

User Sends Message

User sends a message via chat widget or API

Human Agent Takeover

Human agent clicks "Take Over" in dashboard for this conversation

Human Agent Replies

Human agent sends a message through the dashboard

Webhook Triggered

Aksita sends POST request to your webhook URL with optional HMAC signature

Your Server Processes

Verify signature (if configured), process payload, respond with 200 OK