Webhooks Integration Guide

Set up real-time event notifications to keep your systems in sync with Chatplugify activities. Receive instant updates when conversations, contacts, or tasks are created or updated.

What are Webhooks?

Webhooks are HTTP callbacks that Chatplugify sends to your application when specific events occur. Instead of continuously polling our API for changes, webhooks allow you to receive real-time notifications instantly when something happens in your workspace.

Real-time Updates

Get notified instantly when events happen

Secure Delivery

HTTPS-only with authentication headers

Automatic Retry

Failed deliveries are retried automatically

Available Events

Chatplugify can notify your application about various events. Here are the available event types:

Conversation Events

conversation.created

A new conversation is started

conversation.updated

A conversation is modified

conversation.completed

A conversation is marked as completed

Contact Events

contact.created

A new contact is added

contact.updated

Contact information is modified

contact.deleted

A contact is removed

Task Events

task.created

A new task is created

task.updated

Task details are modified

task.completed

A task is marked as completed

task.deleted

A task is removed

Order Events

order.requested

A new order is requested

Webhook Payload Format

All webhook requests are sent as HTTP POST requests with a JSON payload. Here's the standard format:

Webhook Payload Example

{
  "event": "conversation.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "conv_123",
    "workspaceId": "ws_456",
    "userId": "user_789",
    "status": "active",
    "metadata": {
      "source": "chat_widget",
      "customerEmail": "user@example.com"
    }
  },
  "webhookId": "webhook_abc"
}

Payload Fields

eventThe type of event that occurred (e.g., "conversation.created")

timestampISO-8601 timestamp when the event occurred

dataThe actual data related to the event (conversation, contact, task, etc.)

webhookIdUnique identifier for the webhook that sent this event

Setting Up Webhooks

Create Your Endpoint

Create an HTTP endpoint in your application that can receive POST requests. Your endpoint should respond with a 200 status code to acknowledge receipt.

Configure in Dashboard

Go to your Chatplugify dashboard, navigate to the Webhooks section, and add your endpoint URL along with the events you want to receive.

Test Your Integration

Use the test feature in the dashboard to send a test webhook to your endpoint and verify it's working correctly.

Handle Events

Process the webhook events in your application logic to update your systems, send notifications, or trigger automated workflows.

Code Examples

Node.js / Express

server.js

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

app.use(express.json());

app.post('/webhooks/chatplugify', (req, res) => {
  const { event, data, timestamp } = req.body;
  
  console.log('Received webhook:', event);
  
  switch(event) {
    case 'conversation.created':
      console.log('New conversation:', data.id);
      // Handle new conversation logic
      break;
      
    case 'contact.created':
      console.log('New contact:', data.email);
      // Handle new contact logic
      break;
      
    case 'task.completed':
      console.log('Task completed:', data.id);
      // Handle task completion logic
      break;
      
    default:
      console.log('Unknown event:', event);
  }
  
  // Always respond with 200 to acknowledge receipt
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

Python / Flask

app.py

from flask import Flask, request, jsonify
import json

app = Flask(__name__)

@app.route('/webhooks/chatplugify', methods=['POST'])
def handle_webhook():
    payload = request.get_json()
    
    event = payload.get('event')
    data = payload.get('data', {})
    timestamp = payload.get('timestamp')
    
    print(f"Received webhook: {event}")
    
    if event == 'conversation.created':
        print(f"New conversation: {data.get('id')}")
        # Handle new conversation logic
        
    elif event == 'contact.created':
        print(f"New contact: {data.get('email')}")
        # Handle new contact logic
        
    elif event == 'task.completed':
        print(f"Task completed: {data.get('id')}")
        # Handle task completion logic
        
    else:
        print(f"Unknown event: {event}")
    
    # Always respond with 200 to acknowledge receipt
    return jsonify({"received": True}), 200

if __name__ == '__main__':
    app.run(debug=True, port=3000)

Next.js API Route

pages/api/webhooks/chatplugify.js

// pages/api/webhooks/chatplugify.js
export default function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  const { event, data, timestamp } = req.body;
  
  console.log('Received webhook:', event);
  
  switch(event) {
    case 'conversation.created':
      console.log('New conversation:', data.id);
      // Handle new conversation logic
      break;
      
    case 'contact.created':
      console.log('New contact:', data.email);
      // Handle new contact logic
      break;
      
    case 'task.completed':
      console.log('Task completed:', data.id);
      // Handle task completion logic
      break;
      
    default:
      console.log('Unknown event:', event);
  }
  
  // Always respond with 200 to acknowledge receipt
  res.status(200).json({ received: true });
}

Security & Best Practices

HTTPS Only

All webhook requests are sent over HTTPS to ensure data security and integrity.

Authentication Headers

Configure custom authentication headers to verify that requests are coming from Chatplugify.

Idempotency

Handle duplicate events gracefully. The same event might be sent multiple times due to retries.

Timeout Handling

Respond within 10 seconds. Requests that time out will be marked as failed and retried.

Error Handling

Failed webhooks will be retried up to 3 times with exponential backoff. Always return appropriate HTTP status codes.

Troubleshooting

Common Issues

Webhook not receiving events

• Check that your endpoint URL is correct and accessible
• Verify your server is running and responding to POST requests
• Ensure your endpoint responds with a 200 status code
• Check firewall settings allow incoming HTTPS requests

Webhook timing out

• Ensure your endpoint responds within 10 seconds
• Process webhook events asynchronously if they take time
• Return a 200 response immediately and queue processing

Duplicate events

• Implement idempotency using unique event IDs
• Store processed event IDs to avoid duplicate processing
• This is normal behavior due to our retry mechanism

Ready to Set Up Webhooks?

Head to your dashboard to configure your first webhook and start receiving real-time notifications.

Go to Dashboard Next: Data Sources Guide