Webhooks Guide

Webhooks allow you to receive real-time notifications when events occur in WorkFlux. This enables you to build custom integrations and workflows that respond instantly to changes.

Event Types:

• `conversation.started` - New conversation initiated

• `conversation.completed` - Conversation ended

• `conversation.escalated` - Conversation escalated to human

• `agent.response` - Agent generated response

• `user.message` - User sent a message

• `escalation.triggered` - Human escalation requested

• `integration.sync` - Data synchronization completed

• `integration.error` - Integration error occurred

• `agent.updated` - Agent configuration updated

Webhook Payload Structure:

```json

{

"event": "conversation.started",

"timestamp": "2024-01-01T12:00:00Z",

"data": {

"conversation_id": "conv-123",

"agent_id": "agent-123",

"agent_name": "Customer Support Agent",

"channel": "chat",

"user_id": "user-456",

"user_email": "user@example.com",

"initial_message": "Hello, I need help"

}

}

```

conversation.completed Event:

```json

{

"event": "conversation.completed",

"timestamp": "2024-01-01T12:05:00Z",

"data": {

"conversation_id": "conv-123",

"agent_id": "agent-123",

"duration_seconds": 300,

"messages_count": 8,

"resolution_rate": 1.0,

"satisfaction_score": 5,

"was_escalated": false

}

}

```

agent.response Event:

```json

{

"event": "agent.response",

"timestamp": "2024-01-01T12:01:00Z",

"data": {

"conversation_id": "conv-123",

"agent_id": "agent-123",

"message_id": "msg-789",

"content": "I can help you with that...",

"response_time_ms": 1200,

"confidence_score": 0.95

}

}

```

integration.sync Event:

```json

{

"event": "integration.sync",

"timestamp": "2024-01-01T12:00:00Z",

"data": {

"integration_id": "int-456",

"integration_type": "salesforce",

"sync_type": "full",

"records_synced": 150,

"duration_seconds": 45,

"status": "success"

}

}

```

Webhook Signature Verification:

```python

import hmac

import hashlib

def verify_webhook_signature(payload, signature, secret):

expected_signature = hmac.new(

secret.encode(),

payload.encode(),

hashlib.sha256

).hexdigest()

return hmac.compare_digest(expected_signature, signature)

# In your webhook handler:

signature = request.headers.get('X-Workflux-Signature')

if not verify_webhook_signature(request.body, signature, WEBHOOK_SECRET):

return Response('Invalid signature', status=401)

```

Webhook Retry Logic:

```

# WorkFlux retry schedule:

# Attempt 1: Immediate

# Attempt 2: 1 minute

# Attempt 3: 5 minutes

# Attempt 4: 15 minutes

# Attempt 5: 1 hour

# After 5 failed attempts, webhook is disabled

# Response codes that trigger retry:

# - 408 Request Timeout

# - 429 Too Many Requests

# - 500 Internal Server Error

# - 502 Bad Gateway

# - 503 Service Unavailable

# - 504 Gateway Timeout

# Response codes that don't retry:

# - 200 OK (success)

# - 400 Bad Request (client error)

# - 401 Unauthorized (auth error)

# - 404 Not Found

```

1. Create webhook endpoint in your application

2. Configure webhook URL in WorkFlux dashboard

3. Verify webhook signature

4. Test with sample events

5. Monitor delivery status

• All webhooks include signature verification

• Use HTTPS endpoints only

• Validate webhook payloads

• Implement idempotency for duplicate events