Webhooks

Webhooks let you receive real-time notifications when events occur in your Agentix agents. Use them to sync data with your CRM, trigger workflows, or log analytics.

Overview

When configured, Agentix sends HTTP POST requests to your specified URL whenever certain events occur. Each webhook delivery includes the event type, timestamp, and relevant payload.

Configuring Webhooks

Via Dashboard

Navigate to Settings > Webhooks
Click Add Webhook
Enter your endpoint URL
Select the events you want to receive
(Optional) Set a secret for signature verification
Click Save

Webhook URL Requirements

Must be a publicly accessible HTTPS URL
Must respond with a 2xx status code within 10 seconds
Must accept POST requests with Content-Type: application/json

Events

Event	Description
`conversation.created`	A new conversation was started
`conversation.completed`	A conversation was marked as complete
`message.created`	A new message was sent or received
`lead.captured`	A visitor provided their contact information
`rating.submitted`	A visitor rated a conversation
`handoff.requested`	An agent requested human handoff
`handoff.completed`	A human handoff was completed

Payload Format

All webhook payloads follow this structure:


{
  "id": "evt_abc123",
  "type": "lead.captured",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "agentId": "agent_xyz",
  "organizationId": "org_123",
  "data": {
    // Event-specific payload
  }
}

Common Fields

Field	Type	Description
`id`	`string`	Unique event ID (for deduplication)
`type`	`string`	Event type
`timestamp`	`string`	ISO 8601 timestamp
`agentId`	`string`	Agent that generated the event
`organizationId`	`string`	Organization ID
`data`	`object`	Event-specific payload

Event Payloads

conversation.created


{
  "type": "conversation.created",
  "data": {
    "conversationId": "conv_abc",
    "sessionId": "session-001",
    "source": "widget",
    "visitor": {
      "id": "visitor_123",
      "email": "user@example.com",
      "name": "John"
    }
  }
}

lead.captured


{
  "type": "lead.captured",
  "data": {
    "conversationId": "conv_abc",
    "email": "user@example.com",
    "name": "John Doe",
    "phone": "+1234567890",
    "metadata": {
      "source": "widget",
      "page": "https://example.com/pricing"
    }
  }
}

message.created


{
  "type": "message.created",
  "data": {
    "conversationId": "conv_abc",
    "messageId": "msg_xyz",
    "role": "assistant",
    "content": "Here are the products I found...",
    "tokens": 150,
    "responseTime": 2300
  }
}

rating.submitted


{
  "type": "rating.submitted",
  "data": {
    "conversationId": "conv_abc",
    "rating": 5,
    "feedback": "Very helpful!",
    "visitorEmail": "user@example.com"
  }
}

handoff.requested


{
  "type": "handoff.requested",
  "data": {
    "conversationId": "conv_abc",
    "reason": "Customer requested to speak with a human",
    "priority": "normal",
    "visitorEmail": "user@example.com",
    "messageCount": 8
  }
}

Signature Verification

When you set a webhook secret, every delivery includes an X-Agentix-Signature header containing an HMAC-SHA256 signature of the request body.

Verifying in Node.js


import crypto from 'node:crypto'
 
function verifyWebhookSignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex')
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}
 
// Express middleware example
app.post('/webhooks/agentix', (req, res) => {
  const signature = req.headers['x-agentix-signature']
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  )
 
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' })
  }
 
  // Process the event
  const event = req.body
  console.log(`Received: ${event.type}`)
 
  res.status(200).json({ received: true })
})

Verifying in Python


import hmac
import hashlib
 
def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Retry Behavior

If your endpoint fails to respond with a 2xx status within 10 seconds, Agentix retries the delivery:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours

After 5 failed retries, the event is dropped and a notification is sent to the organization admin.

Best Practices

Respond quickly. Return 200 immediately and process the event asynchronously. Do not perform long-running operations in the webhook handler.
Handle duplicates. Use the id field to deduplicate events. The same event may be delivered more than once.
Verify signatures. Always verify the X-Agentix-Signature header to ensure requests come from Agentix.
Use HTTPS. Webhook URLs must use HTTPS to protect payload data in transit.
Monitor failures. Check the webhook delivery logs in the dashboard to identify and fix endpoint issues.

Testing Webhooks

Use the Test button in the dashboard to send a sample payload to your endpoint. You can also use tools like webhook.site or ngrok for local development.


# Example: local testing with ngrok
ngrok http 3000
 
# Then use the ngrok URL as your webhook endpoint:
# https://abc123.ngrok.io/webhooks/agentix