Webhooks

Receive real-time HTTP POST requests when events occur in Chatmefy.

How Webhooks Work

1.An event occurs in Chatmefy (new lead, conversation, etc.)
2.Chatmefy sends an HTTP POST request to your endpoint
3.Your server processes the data and responds with 200 OK
4.If your server fails, we retry up to 3 times

Available Events

lead.created

New lead captured

lead.updated

Lead score or data updated

conversation.started

New conversation began

conversation.ended

Conversation closed

conversation.handoff

Human handoff requested

message.sent

Bot sent a message

message.received

Visitor sent a message

Payload Format

POST https://your-server.com/webhook

{
  "event": "lead.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "lead_abc123xyz",
    "email": "john@company.com",
    "name": "John Smith",
    "phone": "+1234567890",
    "company": "Acme Corp",
    "score": 85,
    "source": {
      "url": "https://yoursite.com/pricing",
      "referrer": "https://google.com",
      "campaign": "google_ads"
    },
    "custom_fields": {
      "company_size": "51-200",
      "budget": "$10k-50k",
      "timeline": "This quarter"
    },
    "conversation_id": "conv_xyz789abc",
    "bot_id": "bot_123",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Security & Verification

Verify webhook authenticity using the signature header:

X-Chatmefy-Signature: sha256=abc123...

Verification Example (Node.js)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return `sha256=${digest}` === signature;
}

// In your handler:
const isValid = verifyWebhook(
  JSON.stringify(req.body),
  req.headers['x-chatmefy-signature'],
  process.env.WEBHOOK_SECRET
);

if (!isValid) {
  return res.status(401).send('Invalid signature');
}

Retry Behavior

Retry Schedule

If your endpoint returns non-2xx or times out, we retry:

• Retry 1: After 1 minute
• Retry 2: After 5 minutes
• Retry 3: After 30 minutes

Timeout

Your endpoint must respond within 30 seconds.

Expected Response

Return HTTP 200-299 to acknowledge receipt. Response body is ignored.

Setup Instructions

1.Go to Settings → Integrations → Webhooks
2.Click 'Add Webhook Endpoint'
3.Enter your HTTPS endpoint URL
4.Select events to subscribe to
5.Copy the generated webhook secret
6.Implement signature verification in your handler
7.Click 'Test' to send a sample event
8.Enable the webhook when ready

Next Steps

API Documentation JavaScript SDK